Scripting Manual

There is no way to explicitly control this type conversion, but it most likely will be changed 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 1s1d90039
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 a 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 "1day 1day 1day"
3d
[admin@MikroTik] > :put "1day day 1day"
1day day 1day
[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)

Common Commands

Description

[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  information about variables
	  log  add entry in the system logs
[admin@MikroTik] > :

• :put - takes only one, unnamed argument. It is displayed on the screen. Cannot be used in scripts, because scripts don't have a place to display values on.
• :if - this is a conditional, or branching command. It has one unnamed argument which must be a condition, id est an expression that must return boolean 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 "gw unreachable"}
10.0.0.1 pong timeout
1 packets transmitted, 0 packets received, 100% packet loss
gw unreachable
[admin@MikroTik] >

• :while - this command has one unnamed argument, a condition. It is evaluated every time before executing do statement. If result is not a boolean value, error is reported. If the result of condition is true, commands are executed once, and the condition is evaluated again, and this repeats until false.
• :do - It has one unnamed argument, which holds the console commands that must be executed. It is similar to the do statement of other commands. If no other arguments are given, :do just executes these commands 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, do statement is 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. However, :do A if=B and :if B do=A do exactly the same thing.
• :for - It has one unnamed argument, the name of the loop variable. from argument is the starting value for the loop counter, to value is the final value. This command counts loop variable up or down starting at from and ending with to, inclusive, and for each value it executes the do statement. It is possible to change the increment from the default 1 (or -1), by specifying the step argument.

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

• :foreach - The unnamed argument is the name of the loop variable. in argument is treated as a list. Each value in sequence is assigned to the loop variable, and do statement is executed for this value. If in value is not a list, do statement is executed only once. If in value is empty, do statement isn't executed at all. This is made to work good with find command, 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 to 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] >
  

Special Commands

Monitor

Get

Notes

Names of properties that can be accessed by get are the same as shown by print command, plus names of item flags (like the disabled in the example below). You can use tab key completions to see what properties any particular get command can return.

Monitor Example

[admin@MikroTik] > /interface
[admin@MikroTik] 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
[admin@kzd] interface>

Get Example

[admin@MikroTik] interface> :put [/interface get ether1  disabled ]
true
[admin@MikroTik] interface>

[admin@MikroTik] interface> :put [/system clock get time ]
feb/28/2003 12:44:39
[admin@MikroTik] interface>

Additional Features

It is possible to put multiple commands on a 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 a 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

Scripts

Description

• 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

Property Description

Notes

You can execute a script by using the run command.

Example

[admin@MikroTik] system script> add name=log-test source={:log message=hello}
[admin@MikroTik] system script> print
  0 name="log-test" source=":log message=hello" owner="admin"
    policy=reboot,read,write,policy,test run-count=0

[admin@MikroTik] system script>

Task Management

Description

Property Description

Example

[admin@MikroTik] system script> add name=DelayeD source={:delay 10m}
[admin@MikroTik] system script> print
  0 name="log-test" source=":log message=hello" owner=admin
    last-started=feb/27/2003 11:05:19 run-count=1

  1 name="DelayD" source=":delay 10m" owner="admin"
    policy=reboot,read,write,policy,test run-count=0
[admin@MikroTik] system script> run DelayeD
[admin@MikroTik] system script> job print
  # SCRIPT  OWNER                   STARTED
  0 DelayeD admin                   feb/27/2003 11:17:33

[admin@MikroTik] system script>

[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=hello" owner="admin"
    policy=reboot,read,write,policy,test last-started=feb/27/2003 11:05:13
    run-count=1

  1 name="DelayD" source=":delay 10m" owner="admin"
    policy=reboot,read,write,policy,test last-started=feb/27/2003 11:17:33
    run-count=1

[admin@MikroTik] system script>

Script Editor

Description

Special Keys

Notes

Editor works only on VT102 compatible terminals (terminal names "vt102", "linux", "xterm", "rxvt" are recognized as VT102 at the moment). Delete, backspace and cursor keys might not work with all terminal programs, use 'Ctrl' alternatives in such cases.

Example

The following example shows the process of sript editing using edit command:

This script is used for writing message "hello" and 3 messages "kuku" to the system log.

Network Watching Tool

Specifications

Description

Property Description

Example

[admin@MikroTik] system script> add name=gw_1 source={/ip route set
{... [/ip route find dst 0.0.0.0] gateway 10.0.0.1}
[admin@MikroTik] system script> add name=gw_2 source={/ip route set 
{.. [/ip route find dst 0.0.0.0] gateway 10.0.0.217}
[admin@MikroTik] system script> /tool netwatch
[admin@MikroTik] tool netwatch> add host=10.0.0.217 interval=10s timeout=998ms \
\... up-script=gw_2 down-script=gw_1
[admin@MikroTik] tool netwatch> print
Flags: X - disabled
  #   HOST	      TIMEOUT		   INTERVAL		STATUS
  0   10.0.0.217      997ms		   10s			up
[admin@MikroTik] tool netwatch> print detail
Flags: X - disabled
  0   host=10.0.0.217 timeout=997ms interval=10s since=feb/27/2003 14:01:03
      status=up up-script=gw_2 down-script=gw_1

[admin@MikroTik] tool netwatch>

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 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

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

[admin@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"}
[admin@MikroTik] system script> 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"}
[admin@MikroTik] system script>
[admin@MikroTik] system script> /tool netwatch
[admin@MikroTik] system netwatch> add host=10.0.0.215 timeout=999ms \
\... interval=20s up-script=e-up down-script=e-down
[admin@MikroTik] tool netwatch> print detail
Flags: X - disabled
  0   host=10.0.0.215 timeout=998ms interval=20s since=feb/27/2003 14:15:36
      status=up up-script=e-up down-script=e-down

[admin@MikroTik] tool netwatch>

System Scheduler

Specifications

Description

Property Description

Notes

If more than one script has to be executed at one time, they are executed in the order they appear in the scheduler configuration. This can be important if, for example, one scheduled script is used to disable another. The order of scripts can be changed with the move command.

If a more complex execution pattern is needed, it can usually be done by scheduling several scripts, and making them enable and disable each other.

Example

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

[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add name=run-1h interval=1h script=log-test
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      SCRIPT   START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   run-1h    log-test oct/30/2008 15:08:22   1h                   1
[admin@MikroTik] system scheduler>

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

[admin@MikroTik] queue simple> /system script
[admin@MikroTik] system script> add name=start_limit source={/queue simple set \
\... Cust0 limit-at=64000}
[admin@MikroTik] system script> add name=stop_limit source={/queue simple set \
\... Cust0 limit-at=128000}
[admin@MikroTik] system script> print
  0 name="start_limit" source="/queue simple set Cust0 limit-at=64000"
    owner=admin run-count=0

  1 name="stop_limit" source="/queue simple set Cust0 limit-at=128000"
    owner=admin run-count=0

[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add interval=24h name="set-64k" \
\... start-time=9:00:00 script=start_limit
[admin@MikroTik] system scheduler> add interval=24h name="set-128k" \
\... start-time=17:00:00 script=stop_limit
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      SCRIPT   START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   set-64k   start... oct/30/2008 09:00:00   1d                   0
  1   set-128k  stop_... oct/30/2008 17:00:00   1d                   0
[admin@MikroTik] system scheduler>

[admin@MikroTik] system script> add name=e-backup source={/system backup
{... save name=email; /tool e-mail send to="root@host.com" subject=[/system
{... identity get name]" Backup" file=email.backup}
[admin@MikroTik] system script> print
  0 name="e-backup" source="/system backup save name=ema... owner=admin
    run-count=0

[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add interval=7d name="email-backup" \
\... script=e-backup
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      SCRIPT   START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   email-... e-backup oct/30/2008 15:19:28   7d                   1
[admin@MikroTik] system scheduler>

[admin@MikroTik] tool e-mail> set server=159.148.147.198 from=SysAdmin@host.com
[admin@MikroTik] tool e-mail> print
    server: 159.148.147.198
      from: SysAdmin@host.com
[admin@MikroTik] tool e-mail>

[admin@MikroTik] system script> add name=enable-x source={/system scheduler
{... enable x}
[admin@MikroTik] system script> add name=disable-x source={/system scheduler
{... disable x}
[admin@MikroTik] system script> add name=log-x source={:log message=x}
[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add name=x-up start-time=00:00:00 \
\... interval=24h script=enable-x
[admin@MikroTik] system scheduler> add name=x-down start-time=12:00:00
\... interval=24h script=disable-x
[admin@MikroTik] system scheduler> add name=x start-time=00:00:00 interval=1h \
\... script=log-x
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      SCRIPT   START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   x-up      enable-x oct/30/2008 00:00:00   1d                   0
  1   x-down    disab... oct/30/2008 12:00:00   1d                   0
  2   x         log-x    oct/30/2008 00:00:00   1h                   0
[admin@MikroTik] system scheduler>

Traffic Monitor

Specifications

Description

Property Description

Example

[admin@MikroTik] system script> add name=eth-up source={/interface enable ether2}
[admin@MikroTik] system script> add name=eth-down source={/interface disable
{... ether2}
[admin@MikroTik] system script> /tool traffic-monitor
[admin@MikroTik] tool traffic-monitor> add name=turn_on interface=ether1 \
\... on-event=eth-up threshold=15000 trigger=above traffic=received
[admin@MikroTik] tool traffic-monitor> add name=turn_off interface=ether1 \
\... on-event=eth-down threshold=12000 trigger=below traffic=received
[admin@MikroTik] tool traffic-monitor> print
Flags: X - disabled, I - invalid
  #   NAME           INTERFACE     TRAFFIC     TRIGGER THRESHOLD  ON-EVENT
  0   turn_on        ether1        received    above   15000      eth-up
  1   turn_off       ether1        received    below   12000      eth-down
[admin@MikroTik] tool traffic-monitor>

Sigwatch

Specifications

Description

Property Description

Notes

Example

[admin@10.179] tool sigwatch> pr
Flags: X - disabled
  #   NAME                                  PORT    SIGNAL     ON-CONDITION LOG
  0   test                                  serial1 cts        change       no

[admin@MikroTik] tool sigwatch>

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=1 state=on

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=1 state=on

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=2 state=off

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=2 state=off

[admin@MikroTik] tool sigwatch>

[admin@MikroTik] port> print stats
  0 name="serial0" line-state=dtr,rts

  1 name="serial1" line-state=dtr,rts
[admin@MikroTik] port>

[admin@MikroTik] port> print stats
  0 name="serial0" line-state=dtr,rts

  1 name="serial1" line-state=dtr,rts,cts
[admin@MikroTik] port>

The example below will execute a script whenever on-condition changes to off:

[admin@10.MikroTik] tool sigwatch> pr detail
Flags: X - disabled
  0   name="cts_rest" port=serial1 signal=cts on-condition=off log=no
      script=/system shutdown count=0 state=on