...
This manual provides an introduction to RouterOS's built-in powerful scripting language.
...
Single command inside (), [] or {} does not require any end of command character. End The end of the command is determined by the content of the whole script
...
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:
- unixUnix – ASCII LF;
- windowsWindows – ASCII CR LF;
- mac – ASCII CR;
Standard C conventions for new-line newline characters can be used ( the \n character).
...
| Code Block | ||
|---|---|---|
| ||
:put (192.168.88.77&0.0.0.255); |
Use the "|" operator and inverted CIDR mask to calculate the broadcast address:
...
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:
| Code Block | ||
|---|---|---|
| ||
#valid variable name :local myVar; #invalid variable name :local my-var; #valid because double quoted :global "my-var"; |
...
| Code Block | ||
|---|---|---|
| ||
#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.
| Code Block | ||
|---|---|---|
| ||
:local myVar "hello" # following line will generate error, because variable myVAr is not defined :put $myVAr # correct code :put $myVar |
...
But will work with different defined variablevariables:
| Code Block | ||
|---|---|---|
| ||
{
:local customname "ether1";
/interface print where name=$customname;
} |
...
| Command | Syntax | Description | Example |
|---|---|---|---|
| / | 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 | |
| delay | :delay <time> | do nothing for a given period of time | |
| put | :put <expression> | put supplied argument to console | |
| len | :len <expression> | return string length or array element count | :put [:len "length=8"]; |
| typeof | :typeof <var> | the return data type of variable | :put [:typeof 4]; |
| pick | :pick <var> <start>[<end>] | return range of elements or substring. If the end position is not specified, will return only one element from an array. | :put [:pick "abcde" 1 3] |
| log | :log <topic> <message> | write a message to the system log. Available topics are "debug, error, info and warning" | :log info "Hello from script"; |
| time | :time <expression> | return interval of time needed to execute the command | :put [:time {:for i from=1 to=10 do={ :delay 100ms }}]; |
| set | :set <var> [<value>] | assign value to a declared variable. | :global a; :set a true; |
| find | :find <arg> <arg> <start> | return position of a substring or array element | :put [:find "abc" "a" -1]; |
| environment | :environment print <start> | print initialized variable information | :global myVar true; :environment print; |
| terminal | terminal related commands | ||
| 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. | {
:local j [:execute {/interface print follow where [:log info ~Sname~]}];
:delay 10s;
:do { /system script job remove $j } on-error={}
} |
| parse | :parse <expression> | parse the string and return parsed console commands. Can be used as a function. | :global myFunc [:parse ":put hello!"]; |
| resolve | :resolve <arg> | return the IP address of the given DNS name | :put [:resolve "www.mikrotik.com"]; |
| rndnum | :rndnum from=[num] to=[num] | random number generator | :put [:rndnum from=1 to=99]; |
| rndstr | :rndstr from=[str] length=[num] | random string generator |
|
| toarray | :toarray <var> | convert variable to the array | |
| tobool | :tobool <var> | convert variable to boolean | |
| toid | :toid <var> | convert variable to internal ID | |
| toip | :toip <var> | convert variable to IP address | |
| toip6 | :toip6 <var> | convert variable to IPv6 address | |
| tonum | :tonum <var> | convert variable to an integer | |
| tostr | :tostr <var> | convert variable to a string | |
| totime | :totime <var> | convert variable to time |
...
| Command | Syntax | Description |
|---|---|---|
| add | add <param>=<value>..<param>=<value> | add new item |
| remove | remove <id> | remove selected item |
| enable | enable <id> | enable selected item |
| disable | disable <id> | disable selected item |
| set | set <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. Example: |
| get | get <id> <param>=<value> | get selected items parameter value |
print <param><param>=[<value>] | print menu items. Output depends on print parameters specified. Most The most common print parameters are described here | |
| export | export [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 file with extension '.rsc', otherwise the output will be printed to console. Exported commands can be imported by import command |
| edit | edit <id> <param> | edit selected items property in the built-in text editor |
| find | find <expression> | Returns list of internal numbers for items that are matched by given expression. For example: :put [/interface find name~"ether"] |
...
| Parameter | Description | Example |
|---|---|---|
| append | ||
| as-value | print output as an array of parameters and its values | :put [/ip address print as-value] |
| brief | print brief description | |
| detail | print detailed description, the output is not as readable as brief output but may be useful to view all parameters | |
| count-only | print only count of menu items | |
| file | print output to file | |
| follow | print all current entries and track new entries until ctrl-c is pressed, very useful when viewing log entries | /log print follow |
| follow-only | print and track only new entries until ctrl-c is pressed, very useful when viewing log entries | /log print follow-only |
| from | print parameters only from specified item | /user print from=admin |
| interval | continuously print output in a selected time interval, useful to track down changes where follow is not acceptable | /interface print interval=2 |
| terse | show details in a compact and machine-friendly format | |
| value-list | show values one per line (good for parsing purposes) | |
| without-paging | If the output does not fit in the console screen then do not stop, print all information in one piece | |
| where | expressions followed by where parameter parameters can be used to filter outmatched entries | /ip route print where interface="ether1" |
...
| Code Block | ||
|---|---|---|
| ||
#add script /system script add name=myScript source=":put \"Hello $myVar !\"" :global myFunc [:parse [/system script get myScript source]] $myFunc myVar=world output: Hello world ! |
...
| Warning |
|---|
| 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:
| Code Block | ||
|---|---|---|
| ||
:global my2 "123"
:global myFunc do={ :global my2; :put $my2; :set my2 "lala"; :put $my2 }
$myFunc my2=1234
:put "global value $my2" |
...
Loop through keys and values
"foreach" command can be used to loop through keys and elements:
| Code Block | ||
|---|---|---|
| ||
[admin@ce0] > :foreach k,v in={2; "aX"=1 ; y=2; 5} do={:put ("$k=$v")}
0=2
1=5
aX=1
y=2 |
If for each the "foreach" command is used with one argument, then the element value will be returned:
...
Sub-menu level: /system script
Contains all user-created scripts. Scripts can be executed in several different ways:
...
Note: Only scripts (including schedulers, netwatch, etc) with equal or higher permission rights can execute other scripts.
| Property | Description |
|---|---|
| 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: ) | list of applicable policies:
Read more detailed policy descriptions here |
| source (string;) | Script source code |
...