MikroTik RouterOS V2.4 Terminal Console Manual

Document revision 21-Jan-2002
This document applies to the MikroTik RouterOS v2.4

Overview

The Terminal Console is used for accessing the MikroTik Router configuration and management features using text terminals, i.e., remote terminal clients, as well as local monitor and keyboard. The Terminal Console is used for writing scripts. This manual describes the general console operation principles. Please consult the Scripting Manual on how to write scripts.

Contents of the Manual

The following topics are covered in this manual:

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 whole lot of available commands, they're split into hierarchy. For example, all (well, almost all) commands that work with routes start with "ip route":

[drax]> ip route print
Flags: X - disabled, I - invalid, D - dynamic, R - rejected 
  #    TYPE        DST-ADDRESS        NEXTHOP... GATEWAY    DISTANCE INTERFACE 
  0    ;;; test multihop route
       static      0.0.0.0/0          A          10.0.0.1   1        ether2    
                                      I          1.1.1.1             (unknown) 
  1 D  connect     10.0.0.0/24        A          0.0.0.0    0        ether2    
  2 D  connect     7.7.7.0/24         A          0.0.0.0    0        tunl        
[drax]> ip route set 0 gateway=10.0.0.1
[drax]> ip route print
Flags: X - disabled, I - invalid, D - dynamic, R - rejected 
  #    TYPE        DST-ADDRESS        NEXTHOP... GATEWAY    DISTANCE INTERFACE 
  0    ;;; test multihop route
       static      0.0.0.0/0          A          10.0.0.1   1        ether2    
  1 D  connect     10.0.0.0/24        A          0.0.0.0    0        ether2    
  2 D  connect     7.7.7.0/24         A          0.0.0.0    0        tunl        

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:

[drax]> ip route
[drax] ip route> print
Flags: X - disabled, I - invalid, D - dynamic, R - rejected 
  #    TYPE        DST-ADDRESS        NEXTHOP... GATEWAY    DISTANCE INTERFACE 
  0    ;;; test multihop route
       static      0.0.0.0/0          A          10.0.0.1   1        ether2    
  1 D  connect     10.0.0.0/24        A          0.0.0.0    0        ether2    
  2 D  connect     7.7.7.0/24         A          0.0.0.0    0        tunl        

...etc

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

[drax] ip route> /
[drax]>

To move up one command level, type ".."

[drax] ip route> ..
[drax] ip>

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

[drax] ip route> /ping 10.0.0.10
timeout: ping reply not recieved after 1000 mss
timeout: ping reply not recieved after 1000 mss
2 packets transmitted, 0 packets received, 100% packet loss

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

[drax] ip route> .. .. ping 10.0.0.10
10.0.0.10 pong: ttl=128 time=1 ms
10.0.0.10 pong: ttl=128 time<1 ms
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0/0.5/1 ms
[drax] ip route>

Lists

Many of the command levels operate with arrays of items: interfaces, routes, users etc. Such arrays are displayed in similarly looking lists. All items in the list have an item number followed by its parameter values. For example:

[drax]> interface print
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0 X ether1               1500  ether                                         
  1   ether2               1500  ether                                         
  2 X pptp-in1                   pptp-in                                       
  3   tunl                 1500  eoip-tunnel                                   

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

[drax]> interface set 1 mtu=1460
[drax]> interface print
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0 X ether1               1500  ether                                         
  1   ether2               1460  ether                                         
  2 X pptp-in1                   pptp-in                                       
  3   tunl                 1500  eoip-tunnel                                   

Numbers are assigned by "print" command and are not constant - it is possible that two successive "print" commands will order items differently. Thus, you must use the print command before any other command that works with list items, to assign numbers.

Note: Although numbers can change each time you use the "print" command, they don't change between these uses. Once assigned, 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 "ip address print" hasn't been executed already. In this case:

[drax]> ip address set 1 netmask=255.255.0.0
ERROR: item numbers not assigned

Console is telling that there has been no "ip address print" command, and thus, it cannot know which address number 1 corresponds to.

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

[drax]> interface print from=1
  #   NAME                 MTU   TYPE                                          
  0   ether2               1460  ether                                         

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" by number 0.

Item names

Some lists have items that have specific names assigned to each. Examples are "interface" or "user" levels. There you can use item names instead of numbers:

[drax]> interface set ether2 mtu 1500

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. Also, [tab] completions work on item names, making them easy to type.

Quick Typing

There are two features in router console that help entering commands much quicker and easier - the [Tab] key completions, and abbreviations of command names. Completions work similarly to the bash shell in UNIX. If you press the [Tab] key after part of a word, console tries to find the command in current context that begins with this word. If there's only one match, it is automatically appended, followed by space character:

/inte_ becomes /interface _

Here, "_" is the cursor position.

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_

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:

[drax]> /interface set e_
[drax]> /interface set ether_
[drax]> /interface set ether
ether1 ether5
[drax]> /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.

New in V2.4: It is now possible to complete not only beginning, but also any distinctive substring of name. When is pressed, console builds list of all possible words that can be entered at current cursor position. It then looks for words that begin with string immediately before cursor. If there is more that one match, then second key will display them in a compact table form. If there's a single match, then it is completed at cursor position. Otherwise, console starts to look 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:

[drax]> /interface x_
[drax]> /interface export _

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

[drax]> /interface mt_
[drax]> /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:

[drax]> ip f st r 1

equals to typing:

[drax]> ip firewall static-nat remove 1

and:

[drax]> pi 10.1 c 3 s 100

equals to:

[drax]> ping 10.0.0.1 count 3 size 100

Help

The console has a built-in help, which can be accessed by typing '?'. General rule is that help shows what you can type in position where the '?' was pressed (similarly to pressing tab key twice, but in verbose form and with explanations).

Internal item numbers

Items can also be addressed by their internal numbers. These numbers are generated by console for scripting purposes and, as the name implies, are used internally. Although you can see them if you print return values of some commands (internal numbers look like hex number preceded by '*' - for example "*100A"), there's no reason for you to type them in manually. Use of invalid internal numbers can result in severe injury of your router configuration.

Multiple items

You can specify multiple items as targets of some commands. Almost everywhere, where you can write the number of items, you can also write a list of numbers:

[drax]> interface print
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0   ether1               1500  ether                                         
  1   ether2               1500  ether                                         
[drax]> interface set "0 1" mtu=1600
[drax]> interface print
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0   ether1               1600  ether                                         
  1   ether2               1600  ether                                         

Note: In the example above, "0 1" could be substituted with "0,1". Lists can be entered either whitespace separated, in quotes, or comma separated. In later case quotes are not required.

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.

Return values

The router console has limited scripting capability. The syntax is simple and similar to TCL. The commands "find" and "get" can be found in many command levels. These commands do not print anything on screen, but create return values that can be used by other console commands. The "find" command creates a return value that contains internal numbers of all items that match parameters of the "find" command. This return value can be used in another command, by placing "find" in square brackets:

[drax]> interface
[drax] interface> print from=[find name=ether2]
  #   NAME                 MTU   TYPE
  0   ether2               1600  ether
[drax] interface> set 0 mtu 1460
[drax] interface> print from=[find mtu=1460]
  #   NAME                 MTU   TYPE
  0   ether2               1460  ether

If you don't give "find" any arguments, it returns internal numbers of all items:

[drax] interface> set [find] mtu=1500
[drax] interface> print
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0   ether1               1500  ether                                         
  1   ether2               1500  ether                                         

You can see the return value of "find" command (and other router commands) using ":put" command:

[drax] interface> :put [find]
*1 *2 

These are internal numbers of all router interfaces. Also, there's a trailing space after last number, so you can concatenate results of several "find" commands:

[drax] interface> print from [find][find]
Flags: X - disabled, D - dynamic 
  #   NAME                 MTU   TYPE                                          
  0   ether1               1500  ether                                         
  1   ether2               1500  ether                                         
  3   ether1               1500  ether                                         
  4   ether2               1500  ether                                         

The "get" command allows to access item values that can be seen with "print" command from scripts. It takes two arguments - item number and name of property:

[drax] interface> :put [get 0 name]
ether1

Item numbers cannot be used in scripts, instead use item names or result of "find" command:

[drax] interface> :put [get ether2 type]
ether

Time Setting

In the console time can be entered in various ways. You can use either hours:minutes:seconds form, or a number followed by: If there is no number before the letters, it will be one unit. You also can use numbers with decimal point. Multiple time intervals can be written consequently - they will be summed.

Variables

The console has variables that can store string values. Assigning such a variable is done by ":set" command:

[drax]> :set var1 J.Random.String

If the value is assigned to a non-existing variable, then the variable is created, otherwise current value is replaced. To access the value of variable, you have to type "$" followed by the name of the variable, and it will be replaced by the value of the variable:

[drax]> :put $var1
J.Random.String
[drax]> :put $var1-$var1-yo-ho-ho-$var1
J.Random.String-J.Random.String-yo-ho-ho-J.Random.String

Magic Variable

The magic variable is the "^" (caret). It contains the return value of the last executed command. Not all commands set this value. Commands like "print" or "telnet" don't have any meaningful way to define return value, so they don't modify it. "add" returns internal number of new item. It is used in some export scripts:

[bainug] interface> /ip route 
[bainug] ip route> export 
/ ip route 
add dst-address=0.0.0.0/0 gateway=10.0.0.1,1.1.1.1 prefered-source=0.0.0.0 
comment $^ "test multihop route"
enable $^ 

This script could also be rewritten so that it does not use "^" variable, at the expense of clarity:

/ ip route
set item [add dst-address=0.0.0.0/0 gateway=10.0.0.1,1.1.1.1 \
    prefered-source=0.0.0.0]
comment $item "test multihop route"
enable $item

General Layout of Command Levels

There are two different kinds of command levels. First, there are levels that allow you to work with lists of similar items - routes, interfaces, users and the like. Second, there are levels that allow you to change some general parameters - time, bridge settings etc.

Most command groups have some or all of these commands: print, set remove, add, find, get, export, enable, disable, comment. These commands have similar behavior in all hierarchy.

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. Thus, "print" usually must be executed before any other commands in the same command level.

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, "columns" argument can be set to a list of property names that should be shown in the table. The "without-paging" argument suppresses prompting after each screen of output.

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. Values for unnamed arguments must follow right after the name of the command, and their order can't be changed. Example: in firewall rules, the "set" command has two unnamed arguments - first is the name of chain and second is the number of rule in this chain. "set" returns internal numbers of items it has set up.

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.

New in 2.4: 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.

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. 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. Argument "noresolve" is used to disable reverse resolving of IP addresses if it proves to be problem.

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:

[MikroTik] ip route>                                                           
Flags: X - disabled, I - invalid, D - dynamic, R - rejected 
  #    TYPE        DST-ADDRESS        NEXTHOP... GATEWAY    DISTANCE INTERFACE 
  0    static      0.0.0.0/0          A          10.0.0.1   1        ether1    
  1 X  static      192.168.0.0/16     I          159.148... 1        (unknown) 
  2 I  static      10.1.1.0/24        I          10.0.1.3   1        (unknown) 
  3 D  connect     159.148.24.0/24    A          0.0.0.0    0        ether1    
  4 D  connect     10.0.0.0/24        A          0.0.0.0    0        ether1    
[MikroTik] ip route>

comment

You can add comments to some items. If the item is commented, comments are shown next to the item number before all parameters and prefixed with ";;;":

[Main_GW] ip route> print                                                          
Flags: X - disabled, I - invalid, D - dynamic, R - rejected 
  #    TYPE        DST-ADDRESS        NEXTHOP... GATEWAY    DISTANCE INTERFACE 
  0    ;;; our default gateway
       static      0.0.0.0/0          A          192.168... 1        ispnet    
  1    ;;; to-pptp-client in the branch office
       static      192.168.223.55/32  A          192.168... 1        ispnet    
  3 D  ospf        159.148.36.0/24    A          10.1.0.2   110      rlan      
  4 D  connect     192.168.248.128/25 A          0.0.0.0    0        ispnet    
...


Copyright 1999-2001, MikroTik