Page History

Scripting language manual

...

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.

Command-line

The RouterOS console uses the following command syntax:

...

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

...

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

...

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

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

...

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:

...

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

...

The following rules apply to use 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"$a $b”$b"; } 
:if ($a = true \ # bad comment 
	and $b=false) do={ :put “$a"$a $b”$b"; }
# comment \
	continued –- invalid (syntax error)

Whitespace between tokens

...

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

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

The code above will generate an expected result because the accessibility of variable "b" and its value will end after the end of the scope.

Keywords

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); 
}

Keywords

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

...

...

:put "\48\45\4C\4C\4F\r\nThis\r\nis\r\na\r\ntest";

which will show on the display
HELLO
This
is
a
test


Operators

...

Usual arithmetic operators are supported in the RouterOS scripting language

...

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

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

{ 
:local IP 192.168.88.77; 
:local CIDRnetmask 255.255.255.0; 
:put ($IP&$CIDRnetmask); 
}

...

...

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

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

Other Operators

...

Operator	Description	Example
“[]”	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 expression	Print all routes which 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") 1 [admin@x86] > :put ($aaa->"b") 2

...

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

Note: Starting from v6.2 there 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-loginNote: Variable value size is limited to 4096bytes

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:

...

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:

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

...

Code Block
language ros
:local “my"my-Var”Var"; :set “my"my-Var”Var" "my value"; :put $”my-Var”$"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.

...

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

{
:local j [:execute {/interface print follow where [:log info ~Sname~]}];
:delay 10s;
:do { /system script job remove $j } on-error={}
}

:if ([/system script job print count-only as-value where script=[:jobname] ] > 1) do={
  :error "script instance already running"
  }

[admin@MikroTik] > :put [:pick

{
:local j [:execute {/interface print follow where [:log info ~Sname~]}];
:delay 10s;
:do { /system script job remove $j } on-error={}
}

 "abcde" 1 3]
bc

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

[admin@MikroTik] > :put [:timestamp]
2735w21:41:43.481891543
or
[admin@MikroTik] > :put [:timestamp]
2735w1d21:41:43.481891543
with the day offset

Menu specific commands

Common commands

Following The following commands are available from most sub-menus:

...

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.

...

...

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

...

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

...

• 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 executing a run command or in winbox

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

Read-only status properties:

Menu specific commands

...

See also

• Scripting ExamplesUser-submitted Scripts
• Manual: Scripting Tips and Tricks

...