Scripting language manual

This manual provides an introduction to RouterOS's built-in powerful scripting language.

Scripting host provides a way to automate some router maintenance tasks by means of executing user-defined scripts bounded to some event occurrence.

Scripts can be stored in the Script repository or can be written directly to the console. The events used to trigger script execution include, but are not limited to the System Scheduler, the Traffic Monitoring Tool, and the Netwatch Tool generated events.

If you are already familiar with scripting in RouterOS, you might want to see our Tips & Tricks.

Line structure

The RouterOS script is divided into a number of command lines. Command lines are executed one by one until the end of the script or until a runtime error occurs.


The RouterOS console uses the following command syntax:

[prefix] [path] command [uparam] [param=[value]] .. [param=[value]]

  • [prefix] - ":" or "/" character which indicates if a command is ICE or path. It may not be required.
  • [path] - relative path to the desired menu level. It may not be required.
  • command - one of the commands available at the specified menu level.
  • [uparam] - unnamed parameter, must be specified if the command requires it.
  • [params] - a sequence of named parameters followed by respective values

The end of the command line is represented by the token “;” or NEWLINE. Sometimes “;” or NEWLINE is not required to end the command line.

Single command inside (), [] or {} does not require any end-of-command character. The end of the command is determined by the content of the whole script

:if ( true ) do={ :put "lala" }

Each command line inside another command line starts and ends with square brackets "[ ]" (command concatenation).

:put [/ip route get [find gateway=]]; 

Notice that the code above contains three command lines:

  • :put
  • /ip route get
  • find gateway=

Command-line can be constructed from more than one physical line by following line joining rules.

Physical Line

A physical line is a sequence of characters terminated by an end-of-line (EOL) sequence. Any of the standard platform line termination sequences can be used:

  • Unix – ASCII LF;
  • Windows – ASCII CR LF;
  • mac – ASCII CR;

Standard C conventions for newline characters can be used ( the \n character).


The following rules apply to a comment:

  • A comment starts with a hash character (#) and ends at the end of the physical line.
  • RouterOS does not support multiline comments.
  • If a # character appears inside the string it is not considered a comment.
# this is a comment 
# next line comment
:global a; # another valid comment

:global myStr "part of the string # is not a comment"

Line joining

Two or more physical lines may be joined into logical lines using the backslash character (\).

The following rules apply to using backslash as a line-joining tool:

  • A line ending in a backslash cannot carry a comment.
  • A backslash does not continue a comment.
  • A backslash does not continue a token except for string literals.
  • A backslash is illegal elsewhere on a line outside a string literal.
:if ($a = true \
	and $b=false) do={ :put "$a $b"; } 
:if ($a = true \ # bad comment 
	and $b=false) do={ :put "$a $b"; }
# comment \
	continued - invalid (syntax error)

Whitespace between tokens

Whitespace can be used to separate tokens. Whitespace is necessary between two tokens only if their concatenation could be interpreted as a different token. Example:

	:local a true; :local b false;
# whitespace is not required 
	:put (a&&b); 
# whitespace is required  
	:put (a and b); 

Whitespace characters are not allowed

  • between '<parameter>='
  • between 'from=' 'to=' 'step=' 'in=' 'do=' 'else='


:for i from = 1 to = 2 do = { :put $i } 
#correct syntax: 
:for i from=1 to=2 do={ :put $i } 
:for i from= 1 to= 2 do={ :put $i } 

/ip route add gateway = 
/ip route add gateway=

Variables can be used only in certain regions of the script called scopes. These regions determine the visibility of the variable. There are two types of scopes - global and local. A variable declared within a block is accessible only within that block and blocks enclosed by it, and only after the point of declaration.

Global scope

Global scope or root scope is the default scope of the script. It is created automatically and can not be turned off.

Local scope

User can define their own groups to block access to certain variables, these scopes are called local scopes. Each local scope is enclosed in curly braces ("{ }").

	:local a 3;
		:local b 4;  
		:put ($a+$b); 
	} #line below will show variable b in light red color since it is not defined in scope  
	:put ($a+$b); 

In the code above variable, b has local scope and will not be accessible after a closing curly brace.

Each line written in the terminal is treated as local scope

So for example, the defined local variable will not be visible in the next command line and will generate a syntax error

[admin@MikroTik] > :local myVar a;
[admin@MikroTik] > :put $myVar
syntax error (line 1 column 7)
Do not define global variables inside local scopes.

Note that even variable can be defined as global, it will be available only from its scope unless it is not referenced to be visible outside of the scope.

	:local a 3; 
		:global b 4; 
	:put ($a+$b); 

The code above will output 3, because outside of the scope b is not visible. 

The following code will fix the problem and will output 7:

	:local a 3; 
		:global b 4; 
	:global b;  
	:put ($a+$b); 


The following words are keywords and cannot be used as variable and function names:

and       or       in


The following tokens serve as delimiters in the grammar:

()  []  {}  :   ;   $   / 

Data types

RouterOS scripting language has the following data types:

num (number)- 64bit signed integer, possible hexadecimal input;
bool (boolean)- values can bee true or false;
str (string)- character sequence;
ip- IP address;
ip-prefix- IP prefix;
ip6- IPv6 address
ip6-prefix- IPv6 prefix
id (internal ID)- hexadecimal value prefixed by '*' sign. Each menu item has an assigned unique number - internal ID;
time- date and time value;
array- sequence of values organized in an array;
nil- default variable type if no value is assigned;

Constant Escape Sequences

Following escape sequences can be used to define certain special characters within a string:

\"Insert double quote
\\Insert backslash
\nInsert newline
\rInsert carriage return
\tInsert horizontal tab
\$Output $ character. Otherwise, $ is used to link the variable.
\?Output ? character. Otherwise ? is used to print "help" in the console. Removed since v7.1rc2
\_- space
\a- BEL (0x07)
\b- backspace (0x08)
\f- form feed (0xFF)
\vInsert vertical tab
\xxA print character from hex value. Hex numbers should use capital letters.
:put "\48\45\4C\4C\4F\r\nThis\r\nis\r\na\r\ntest";

which will show on the display


Arithmetic Operators

Usual arithmetic operators are supported in the RouterOS scripting language

"+"binary addition:put (3+4);
"-"binary subtraction:put (1-6);
"*"binary multiplication:put (4*5);
"/"binary division:put (10 / 2); :put ((10)/2)
"%"modulo operation:put (5 % 3);
"-"unary negation{ :local a 1; :put (-a); }

Note: for the division to work you have to use braces or spaces around the dividend so it is not mistaken as an IP address

Relational Operators

"<"less:put (3<4);
">"greater:put (3>4);
"="equal:put (2=2);
"<="less or equal
">="greater or equal
"!="not equal

Logical Operators

“!”logical NOT:put (!true);
“&&”, “and”logical AND:put (true&&true)
“||”, “or”logical OR:put (true||false);
:put ( in;

Bitwise Operators

Bitwise operators are working on number, IP, and IPv6 address data types.

“~”bit inversion:put (~
:put (~::ffff)
“|”bitwise OR. Performs logical OR operation on each pair of corresponding bits. In each pair the result is “1” if one of the bits or both bits is “1”, otherwise the result is “0”.:put (|
:put (2001::1|::ffff)
“^”bitwise XOR. The same as OR, but the result in each position is “1” if two bits are not equal, and “0” if the bits are equal.:put (^
:put (2001::ffff:1^::ffff:0)
“&”bitwise AND. In each pair, the result is “1” if the first and second bit is “1”. Otherwise, the result is “0”.:put (
:put (2001::1111&ffff::)
“<<”left shift by a given amount of bits, not supported for IPv6 address data type:put (<<8)
“>>”right shift by a given amount of bits, not supported for IPv6 address data type:put (>>24)

Calculate the subnet address from the given IP and CIDR Netmask using the "&" operator:

:local IP; 
:local CIDRnetmask; 
:put ($IP&$CIDRnetmask); 

Get the last 8 bits from the given IP addresses:

 :put (;

Use the "|" operator and inverted CIDR mask to calculate the broadcast address:

:local IP; 
:local Network; 
:local CIDRnetmask; 
:local InvertedCIDR (~$CIDRnetmask); 
:put ($Network|$InvertedCIDR) 

Concatenation Operators

"."concatenates two strings:put ("concatenate" . " " . "string");
","concatenates two arrays or adds an element to the array:put ({1;2;3} , 5 );

It is possible to add variable values to strings without a concatenation operator:

:global myVar "world"; 

:put ("Hello " . $myVar); 
# next line does the same as above 
:put "Hello $myVar";

By using $[] and $() in the string it is possible to add expressions inside strings:

:local a 5; 
:local b 6; 
:put " 5x6 = $($a * $b)"; 

:put " We have $[ :len [/ip route find] ] routes";

Other Operators

“[]”command substitution. Can contain only a single command line:put [ :len "my test string"; ];
“()”subexpression or grouping operator:put ( "value is " . (4+5));
“$”substitution operator:global a 5; :put $a;
“~”the binary operator that matches value against POSIX extended regular expressionPrint all routes whose gateway ends with 202
/ip route print where gateway~"^[0-9 \\.]*202\$"
“->”Get an array element by key
[admin@x86] >:global aaa {a=1;b=2}
[admin@x86] > :put ($aaa->"a")
[admin@x86] > :put ($aaa->"b")


The scripting language has two types of variables:

  • global - accessible from all scripts created by the current user, defined by global keyword;
  • local - accessible only within the current scope, defined by local keyword.

There can be undefined variables. When a variable is undefined, the parser will try to look for variables set, for example, by DHCP lease-script or Hotspot on-login

Every variable, except for built-in RouterOS variables, must be declared before usage by local or global keywords. Undefined variables will be marked as undefined and will result in a compilation error. Example:

# following code will result in compilation error, because myVar is used without declaration 
:set myVar "my value"; 
:put $myVar

Correct code:

:local myVar; 
:set myVar "my value"; 
:put $myVar;

The exception is when using variables set, for example, by DHCP lease-script

/system script 
add name=myLeaseScript policy=\ 
	ftp,reboot,read,write,policy,test,winbox,password,sniff,sensitive,api \ 
	source=":log info \$leaseActIP\r\ 
	\n:log info \$leaseActMAC\r\ 
	\n:log info \$leaseServerName\r\ 
	\n:log info \$leaseBound" 

/ip dhcp-server set myServer lease-script=myLeaseScript

Valid characters in variable names are letters and digits. If the variable name contains any other character, then the variable name should be put in double quotes. Example:

#valid variable name 
:local myVar; 
#invalid variable name 
:local my-var; 
#valid because double quoted 
:global "my-var";

If a variable is initially defined without value then the variable data type is set to nil, otherwise, a data type is determined automatically by the scripting engine. Sometimes conversion from one data type to another is required. It can be achieved using data conversion commands. Example:

#convert string to array 
:local myStr "1,2,3,4,5"; 
:put [:typeof $myStr]; 
:local myArr [:toarray $myStr]; 
:put [:typeof $myArr]

Variable names are case-sensitive.

:local myVar "hello" 
# following line will generate error, because variable myVAr is not defined 
:put $myVAr 
# correct code 
:put $myVar

Set command without value will un-define the variable (remove from environment, new in v6.2)

#remove variable from environment 
:global myVar "myValue" 
:set myVar;

Use quotes on the full variable name when the name of the variable contains operators. Example:

:local "my-Var";
:set "my-Var" "my value";
:put $"my-Var";

Reserved variable names

All built-in RouterOS properties are reserved variables. Variables that will be defined the same as the RouterOS built-in properties can cause errors. To avoid such errors, use custom designations.

For example, the following script will not work:

:local type "ether1"; 
/interface print where name=$type; 

But will work with different defined variables:

:local customname "ether1"; 
/interface print where name=$customname; 


Global commands

Every global command should start with the ":" token, otherwise, it will be treated as a variable.

go to the root menu
go back by one menu level
list all available menu commands and brief descriptions
global:global <var> [<value>]define a global variable:global myVar "something"; :put $myVar;
local:local <var> [<value>]define the local variable{ :local myLocalVar "I am local"; :put $myVar; }
beep:beep <freq> <length>beep built-in speaker
convert:convert from=[arg] to=[arg]

Converts specified value from one format to another. By default uses an automatically parsed value, if the "from" format is not specified (for example, "001" becomes "1", "10.1" becomes "", etc.).

from specifies the format of the value - base32, base64, hex, raw, rot13, url.

to specifies the format of the output value - base32, base64, hex, raw, rot13, url.

transform to transform values - lc (transforms value to be in lowercases), uc (uppercases), lcfirst (first value to lowercase), ucfirst (first value to uppercase)

:put [:convert 001 to=hex ]


:put [:convert [/ip dhcp-client/option/get hostname raw-value] from=hex to=raw ]


:put [convert transform=lc "AAA"]         


delay:delay <time>do nothing for a given period of time
environment:environment print <start>print initialized variable information:global myVar true; :environment print;
error:error <output>Generate console error and stop executing the script
execute:execute <expression>

Execute the script in the background. The result can be written in the file by setting a "file" parameter or printed to the CLI by setting "as-string".

When using the "as-string" parameter executed script is blocked (not executed in the background).

Executed script can not be larger than 64kB

:local j [:execute {/interface print follow where [:log info ~Sname~]}];
:delay 10s;
:do { /system script job remove $j } on-error={}
find:find <arg> <arg> <start>return position of a substring or array element:put [:find "abc" "a" -1];
:jobnamereturn current script name
Limit script execution to single instance
:if ([/system script job print count-only as-value where script=[:jobname] ] > 1) do={
  :error "script instance already running"

len:len <expression>return string length or array element count:put [:len "length=8"];
log:log <topic> <message>write a message to the system log. Available topics are "debug, error, info and warning":log info "Hello from script";
onerror:onerror <var_name> in={<command>} do={<expression>}

The command used to catch errors and get error details. The do={...} block is executed, when in={...} block has an error,  and error details are written in <var_name> variable. 

Parameter order is important. The "error" parameter must be set before "do" block, otherwise do block will not see the local variable. 

:onerror can return false (if there is no error) and true (if there is an error) values, so it can be used in :if condition statement scripts.

:onerror errorName in={ :error "failure" } do={ :put "Critical $errorName" }
parse:parse <expression>parse the string and return parsed console commands. Can be used as a function.:global myFunc [:parse ":put hello!"];
pick:pick <var> <start>[<count>]

return range of elements or substring. If the count is not specified, will return only one element from an array.

  • var - value to pick elements from
  • start - element to start picking from (the first element index is 0)
  • count - number of elements to pick starting from the first element with index=0

[admin@MikroTik] > :put [:pick "abcde" 1 3]

put:put <expression>put the supplied argument into the console:put "Hello world"
resolve:resolve <arg>return the IP address of the given DNS name:put [:resolve ""];
retry:retry command=<expr> delay=[num] max=[num] on-error=<expr>Try to execute the given command "max" amount of times with a given "delay" between tries. On failure, execute the expression given in the "on-error" block

:retry command={abc} delay=1 max=2 on-error={:put "got error"}
got error

:retry command={abc} delay=1 max=2 on-error={:put "got error"}
got error
typeof:typeof <var>the return data type of variable:put [:typeof 4];
rndnum:rndnum from=[num] to=[num]random number generator:put [:rndnum from=1 to=99];
rndstr:rndstr from=[str] length=[num]

Random string generator.

from specifies characters to construct the string from and defaults to all ASCII letters and numerals.
length specifies the length of the string to create and defaults to 16.

:put [:rndnum from="abcdef%^&" length=33];

set:set <var> [<value>]assign value to a declared variable.:global a; :set a true;
serialize:serialize [<value>] to=[arg]

Serialize specified value/array to JSON or dsv (delimeter separated values) format.

to specifies the format - json, dsv

delimeter sets the "separator".

oder specifies the order for variables.

options specifies additional options - json.pretty (makes the JSON output more visually appealing), dsv.wrap-strings (wraps string values inside quatation marks), dsv.ignore-size (if array values have different sizes, e.g. a=(1,2);b=(3,4);c=(5,6,7),this option will work around array size mismatch error and set "empty" values in those slots).

:put [:serialize value=a,b,c to=json]                 

:local test {a=(1,2,3);b=(4,5,6);c=(7,"text",9)}; :put [ :serialize to=dsv delimiter=";" value=$test order=("c","a","b") ]     

deserialize:deserialize [<value>] from=[arg]

Deserialize specified value/array from JSON or dsv (delimeter separated values) format.

from specifies the format - json, dsv

See "serialize" above for more parameters.

:put [:deserialize from=json value="[\"a\",\"b\",\"c\"]"]
time:time <expression>return interval of time needed to execute the command:put [:time {:for i from=1 to=10 do={ :delay 100ms }}];
timestamp:timestampreturns the time since epoch, where epoch is January 1, 1970 (Thursday), not counting leap seconds
[admin@MikroTik] > :put [:timestamp]
[admin@MikroTik] > :put [:timestamp]
with the day offset
toarray:toarray <var>convert a variable to the array
tobool:tobool <var>convert a variable to boolean
toid:toid <var>convert a variable to internal ID
toip:toip <var>convert a variable to IP address
toip6:toip6 <var>convert a variable to IPv6 address
tonum:tonum <var>convert a variable to an integer
tostr:tostr <var>convert a variable to a string
totime:totime <var>convert a variable to time

Menu specific commands

Common commands

The following commands are available from most sub-menus:

addadd <param>=<value>..<param>=<value>add new item
removeremove <id>remove selected item
enableenable <id>enable selected item
disabledisable <id>disable selected item
setset <id> <param>=<value>..<param>=<value>change selected items parameter, more than one parameter can be specified at the time. The parameter can be unset by specifying '!' before the parameter.

/ip firewall filter add chain=blah action=accept protocol=tcp port=123 nth=4,2
set 0 !port chain=blah2 !nth protocol=udp

getget <id> <param>=<value>get the selected item's parameter value
printprint <param><param>=[<value>]print menu items. Output depends on the print parameters specified. The most common print parameters are described here
exportexport [file=<value>]export configuration from the current menu and its sub-menus (if present). If the file parameter is specified output will be written to the file with the extension '.rsc', otherwise the output will be printed to the console. Exported commands can be imported by import command
editedit <id> <param>edit selected items property in the built-in text editor
findfind <expression>Returns list of internal numbers for items that are matched by given expression. For example:  :put [/interface find name~"ether"]

The import command is available from the root menu and is used to import configuration from files created by an export command or written manually by hand.

print parameters

Several parameters are available for print command:


as-valueprint output as an array of parameters and its values:put [/ip address print as-value]
briefprint brief description
detailprint detailed description, the output is not as readable as brief output but may be useful to view all parameters
count-onlyprint only count of menu items
fileprint output to a file
followprint all current entries and track new entries until ctrl-c is pressed, very useful when viewing log entries/log print follow
follow-onlyprint and track only new entries until ctrl-c is pressed, very useful when viewing log entries/log print follow-only
fromprint parameters only from specified item/user print from=admin
intervalcontinuously print output in a selected time interval, useful to track down changes where follow is not acceptable/interface print interval=2
terseshow details in a compact and machine-friendly format
value-listshow values single per line (good for parsing purposes)
without-pagingIf the output does not fit in the console screen then do not stop, print all information in one piece
whereexpressions followed by where parameters can be used to filter outmatched entries/ip route print where interface="ether1"

More than one parameter can be specified at a time, for example, /ip route print count-only interval=1 where interface="ether1"

Loops and conditional statements


do..while:do { <commands> } while=( <conditions> ); :while ( <conditions> ) do={ <commands> };execute commands until a given condition is met.
for:for <var> from=<int> to=<int> step=<int> do={ <commands> }execute commands over a given number of iterations
foreach:foreach <var> in=<array> do={ <commands> };execute commands for each element in a list

Conditional statement

if:if (<condition>) do={<commands>} else={<commands>} <expression>If a given condition is true then execute commands in the do block, otherwise execute commands in the else block if specified.


	:local myBool true;  
	:if ($myBool = false) do={ :put "value is false" } else={ :put "value is true" } 


Scripting language does not allow you to create functions directly, however, you could use :parse command as a workaround.

Starting from v6.2 new syntax is added to easier define such functions and even pass parameters. It is also possible to return function value with :return command.

See examples below:

#define function and run it
:global myFunc do={:put "hello from function"}

hello from function

#pass arguments to the function
:global myFunc do={:put "arg a=$a"; :put "arg '1'=$1"} 
$myFunc a="this is arg a value" "this is arg1 value"

arg a=this is arg a value
arg '1'=this is arg1 value

Notice that there are two ways how to pass arguments:

  • pass arg with a specific name ("a" in our example)
  • pass value without arg name, in such case arg "1", "2" .. "n" is used.

Return example

:global myFunc do={ :return ($a + $b)} 
:put [$myFunc a=6 b=2] 


You can even clone an existing script from the script environment and use it as a function.

#add script
/system script add name=myScript source=":put \"Hello $myVar !\""

:global myFunc [:parse [/system script get myScript source]]
$myFunc myVar=world

Hello world !
If the function contains a defined global variable that names match the name of the passed parameter, then the globally defined variable is ignored, for compatibility with scripts written for older versions. This feature can change in future versions. Avoid using parameters with the same name as global variables.

For example:

:global my2 "123" 

:global myFunc do={ :global my2; :put $my2; :set my2 "lala"; :put $my2 } 
$myFunc my2=1234 
:put "global value $my2"

The output will be:

global value 123

Nested function example

Note: to call another function its name needs to be declared (the same as for variables)

:global funcA do={ :return 5 } 
:global funcB do={  
	:global funcA;  
	:return ([$funcA] + 4) 
:put [$funcB] 


Catch run-time errors

Starting from v6.2 scripting has the ability to catch run-time errors.

For example, the [code]:reslove[/code] command if failed will throw an error and break the script.

[admin@MikroTik] > { :put [:resolve]; :put "lala";}
failure: dns name does not exist

Now we want to catch this error and proceed with our script:

:do {  
	:put [:resolve]; 
} on-error={ :put "resolver failed"}; 
:put "lala" 


resolver failed 

Operations with Arrays

Warning: Key name in the array contains any character other than a lowercase character, it should be put in quotes

For example:

[admin@ce0] > {:local a { "aX"=1 ; ay=2 }; :put ($a->"aX")} 

Loop through keys and values

"foreach" command can be used to loop through keys and elements:

[admin@ce0] > :foreach k,v in={2; "aX"=1 ; y=2; 5} do={:put ("$k=$v")} 


If the "foreach" command is used with one argument, then the element value will be returned:

[admin@ce0] > :foreach k in={2; "aX"=1 ; y=2; 5} do={:put ("$k")} 


Note: If the array element has a key then these elements are sorted in alphabetical order, elements without keys are moved before elements with keys and their order is not changed (see example above).

Change the value of a single array element

[admin@MikroTik] > :global a {x=1; y=2}
[admin@MikroTik] > :set ($a->"x") 5 
[admin@MikroTik] > :environment print 
a={x=5; y=2}

Script repository

Sub-menu level: /system script

Contains all user-created scripts. Scripts can be executed in several different ways:

  • on event - scripts are executed automatically on some facility events ( scheduler, netwatch, VRRP)
  • by another script - running script within the script is allowed
  • manually - from console executingrun command or in winbox

Note: Only scripts (including schedulers, netwatch, etc) with equal or higher permission rights can execute other scripts.

comment (string; Default: )Descriptive comment for the script
dont-require-permissions (yes | no; Default: no)Bypass permissions check when the script is being executed, useful when scripts are being executed from services that have limited permissions, such as Netwatch
name (string; Default: "Script[num]")name of the script
policy (string; Default: ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon)list of applicable policies:
  • ftp - can log on remotely via FTP and send and retrieve files from the router
  • password - change passwords
  • policy - manage user policies, add and remove user
  • read - can retrieve the configuration
  • reboot - can reboot the router
  • sensitive - allows changing "hide sensitive" parameter
  • sniff - can run sniffer, torch, etc
  • test - can run ping, traceroute, bandwidth test
  • write - can change the configuration

Read more detailed policy descriptions here

source (string;)Script source code

Read-only status properties:

last-started (date)Date and time when the script was last invoked.
owner (string)The user who created the script
run-count (integer)Counter that counts how many times the script has been executed

Menu specific commands

run (run [id|name])Execute the specified script by ID or name


Sub-menu level:

  • /system script environment
  • /environment

Contains all user-defined variables and their assigned values.

[admin@MikroTik] > :global example;
[admin@MikroTik] > :set example 123
[admin@MikroTik] > /environment print  

Read-only status properties:

name (string)Variable name
user (string)The user who defined variable
value ()The value assigned to a variable


Sub-menu level: /system script job

Contains a list of all currently running scripts.
Read-only status properties:

owner (string)The user who is running the script
policy (array)List of all policies applied to the script
started (date)Local date and time when the script was started

See also

  • No labels