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>
[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.
[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.
/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 "x" is completed to "export", because no other word in this context contains
'x'.
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:
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.
If you don't give "find" any arguments, it returns internal numbers of all
items:
You can see the return value of "find" command (and other router commands)
using ":put" command:
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:
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:
Item numbers cannot be used in scripts, instead use item names or result of
"find" command:
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:
This script could also be rewritten so that it does not use "^" variable, at
the expense of clarity:
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:
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 ";;;":
[drax]> /interface x
[drax]> /interface mt
[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
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
[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
[drax] interface> :put [find]
*1 *2
[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
[drax] interface> :put [get 0 name]
ether1
[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:
"d", "da", "day", "days" - for days (86400 seconds each)
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.
"h", "ho" ...
"hours" - for hours (3600 seconds each)
"m", "mi", "min" - for minutes (60
seconds each)
"s" - for seconds
"ms" - for millisecondsVariables
The console has variables that can store string values.
Assigning such a variable is done by ":set" command:
[drax]> :set var1 J.Random.String
[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 $^
/ 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.
[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>
[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