...
Panelcode | |||||
---|---|---|---|---|---|
| 1
|
...
|
...
|
...
|
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.
Command-line
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
Code Block | ||
---|---|---|
|
------------
Scripting language manual
This manual provides an introduction to RouterOS 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 Script repository or can be written directly to 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
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
RouterOS console uses following command syntax:
[prefix] [path] command [uparam] [param=[value]] .. [param=[value]]
- [prefix] - ":" or "/" character which indicates if command is ICE or path. May or may not be required.
- [path] - relative path to the desired menu level. May or may not be required.
- command - one of the commands available at the specified menu level.
- [uparam] - unnamed parameter, must be specified if command requires it.
- [params] - sequence of named parameters followed by respective values
The end of command line is represented by the token “;” or NEWLINE. Sometimes “;” or NEWLINE is not required to end the command line.
...
:if ( true ) do={ :put "lala" } |
...
Each command line inside another command line starts and ends with square brackets "[ ]" (command concatenation).
Code Block | ||
---|---|---|
| ||
:put [/ip route get [find gateway=1.1.1.1]]; |
...
Notice that the code above contains three command lines:
- :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:
...
- Unix – ASCII LF;
...
- Windows – ASCII CR LF;
- mac – ASCII CR;
Standard C conventions for
...
newline characters can be used ( the \n character).
Comments
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.
Example
Code Block | ||
---|---|---|
| ||
# 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.
Example
Code Block | ||
---|---|---|
| ||
: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:
Code Block | ||
---|---|---|
| ||
{ |
...
: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='
Example:
Code Block | ||
---|---|---|
| ||
#incorrect: :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 } |
...
#incorrect /ip route add gateway = 3.3.3.3 #correct /ip route add gateway=3.3.3.3 |
...
Scopes
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 ("{ }").
...
Code Block | ||
---|---|---|
| ||
{ :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.
Note |
---|
...
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)
Warning |
---|
...
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.
Code Block | ||
---|---|---|
| ||
{ :local a 3; { |
...
:global b 4; |
...
} |
...
|
...
:put ($a+$b); } |
...
Code above will generate an error.
Keywords
The following words are keywords and cannot be used as variable and function names:
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:
Code Block | ||
---|---|---|
| ||
{
:local a 3;
{
:global b 4;
}
:global b;
:put ($a+$b);
} |
Keywords
The following words are keywords and cannot be used as variable and function names:
and or and or in
Delimiters
The following tokens serve as delimiters in the grammar:
() [] {} : ; $ /
Data types
RouterOS scripting language has the following data types:
Type | Description |
---|---|
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 |
\n | Insert newline |
\r | Insert carriage return |
\t | Insert horizontal tab |
\$ | Output $ character. Otherwise, $ is used to link the variable. |
\? |
\_ | - space |
\a | - BEL (0x07) |
\b | - backspace (0x08) |
\f | - form feed (0xFF) |
\v | Insert vertical tab |
\xx |
A print character from hex value. Hex |
numbers should use capital letters. |
Example
:put "\48\45\4C\4C\4F\r\nThis\r\nis\r\na\r\ntest";
which will show on the displayHELLO
This
is
a
test
Operators
Arithmetic Operators
Usual arithmetic operators are supported in the RouterOS scripting language
Operator | Description | Example |
---|---|---|
"+" | 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
Operator | Description | Example |
---|---|---|
"<" | less | :put (3<4); |
">" | greater | :put (3>4); |
"=" | equal | :put (2=2); |
"<=" | less or equal | |
">=" | greater or equal | |
"!=" | not equal |
Logical Operators
Operator | Description | Example |
---|---|---|
“!” | logical NOT | :put (!true); |
“&&”, “and” | logical AND | :put (true&&true) |
“||”, “or” | logical OR | :put (true||false); |
“in” | :put (1.1.1.1/32 in 1.0.0.0/8); |
Bitwise Operators
Bitwise operators are working on number, IP, and IPv6 address data types.
Operator | Description | Example |
---|---|---|
“~” | bit inversion | :put (~0.0.0.0) :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 (192.168.88.0|0.0.0.255) :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 (1.1.1.1^255.255.0.0) :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 (192.168.88.77&255.255.255.0) :put (2001::1111&ffff::) |
“<<” | left shift by a given amount of bits, not supported for IPv6 address data type | :put (192.168.88.77<<8) |
“>>” | right shift by a given amount of bits, not supported for IPv6 address data type | :put (192.168.88.77>>24) |
Calculate the subnet address from the given IP and CIDR Netmask using the "&" operator:
Code Block | ||
---|---|---|
| ||
{ :local IP 192.168.88.77; :local CIDRnetmask 255.255.255.0; :put ($IP&$CIDRnetmask); } |
...
Get the last 8 bits from the given IP addresses:
Code Block | ||
---|---|---|
| ||
:put (192.168.88.77&0.0.0.255); |
...
Use the "|" operator and inverted CIDR mask to calculate the broadcast address:
Code Block | ||
---|---|---|
| ||
{ :local IP 192.168.88.77; :local Network 192.168.88.0; :local CIDRnetmask 255.255.255.0; :local InvertedCIDR (~$CIDRnetmask); :put ($Network|$InvertedCIDR) } |
...
Concatenation Operators
Operator | Description | Example |
---|
". |
" | 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:
Code Block | ||
---|---|---|
| ||
: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:
Code Block | ||
---|---|---|
| ||
:local a 5; :local b 6; :put " 5x6 = $($a * $b)"; :put " We have $[ :len [/ip route find] ] routes"; |
...
Other Operators
</tr>
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 |
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 |
Variables
...
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.
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:
Code Block | ||
---|---|---|
| ||
# following code will result in compilation error, because myVar is used without declaration :set myVar "my value"; :put $myVar |
...
Correct code:
Code Block | ||
---|---|---|
| ||
:local myVar; :set myVar "my value"; :put $myVar; |
...
...
The exception is when using variables set, for example, by DHCP lease-script
Code Block | ||
---|---|---|
| ||
/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:
Code Block | ||
---|---|---|
| ||
#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:
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 |
...
Set command without value will un-define the variable (remove from environment, new in v6.2)
Code Block | ||
---|---|---|
| ||
#remove variable from environment :global myVar "myValue" :set myVar; |
...
Reserved variable names
...
Use quotes on the full variable name when the name of the variable contains operators. Example:
Code Block | ||
---|---|---|
| ||
: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:
Code Block | ||
---|---|---|
| ||
{ :local type "ether1"; /interface print |
...
where name=$type;
} |
But will work with different defined variables:
Code Block | ||
---|---|---|
| ||
{
:local customname "ether1";
/interface print where name=$customname;
} |
Commands
Global commands
Every global command should start with the ":" token, otherwise, it will be treated as a variable.
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 | ||||||||
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 "10.0.0.1", 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. |
| |||||||
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 |
| |||||||
find | :find <arg> <arg> <start> | return position of a substring or array element | :put [:find "abc" "a" -1]; | |||||||
jobname | :jobname | return current script name |
| |||||||
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"; | |||||||
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.
|
| |||||||
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 "www.mikrotik.com"]; | |||||||
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"}
| |||||||
typeof | :typeof <var> | the |
But will work with different defined variable:
{
:local customname "ether1";
/interface print where name=$customname;
}
Commands
Global commands
Every global command should start with ":" token, otherwise it will be treated as variable.
:global <var> [<value>]
:global myVar "something"; :put $myVar;
:local <var> [<value>]
{ :local myLocalVar "I am local"; :put $myVar; }
:beep <freq> <length>
:delay <time>
:put <expression>
:len <expression>
:put [:len "length=8"];
:typeof <var>
return data type of variable | :put [:typeof 4]; |
rndnum | : |
rndnum from=[num] to=[num] | random number generator | :put [: |
:log <topic> <message>
"debug, error, info and warning"
:log info "Hello from script";
:time <expression>
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. |
|
| |||
set | :set <var> [<value>] | assign value to a declared variable. | :global a; :set a true; |
:put [:find "abc" "a" -1];
:environment print <start>
:global myVar true; :environment print;
terminal | : |
terminal |
terminal related commands |
time | : |
time <expression> | return interval of time needed to execute the command | :put [:time {:for i from=1 to=10 do={ :delay 100ms }}]; | ||||||
timestamp | :timestamp | returns the time since epoch, where epoch is January 1, 1970 (Thursday), not counting leap seconds |
|
:execute <expression>
{
:local j [:execute {/interface print follow where [:log info ~Sname~]}];
:delay 10s;
:do { /system script job remove $j } on-error={}
}
:parse <expression>
:global myFunc [:parse ":put hello!"];
$myFunc;
:resolve <arg>
:put [:resolve "www.mikrotik.com"];
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:
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 the selected |
item's parameter value | ||
print <param><param>=[<value>] | print menu items. Output depends on the print parameters specified. |
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 the file with the extension '.rsc', otherwise the output will be printed to the 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"] |
import
...
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:
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 a 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 |
single 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 |
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
Loops
Command | Syntax | Description |
---|---|---|
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
Command | Syntax | Description |
---|---|---|
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. |
Example:
Code Block | ||
---|---|---|
| ||
{ |
...
:local myBool true; |
...
|
...
:if ($myBool = false) do={ :put "value is false" } else={ :put "value is true" } } |
...
Functions
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:
Code Block | ||
---|---|---|
| ||
#define function and run it :global myFunc do={:put "hello from function"} $myFunc output: 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"
output:
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
Code Block | ||
---|---|---|
| ||
:global myFunc do={ |
...
:return ($a + $b)} :put [$myFunc a=6 b=2] output: 8 |
...
You can even clone an existing script from the script environment and use it as a function.
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" |
...
...
The output will be:
1234 lala global value 123
Nested function example
Note: to call another function its name needs to be declared (the same as for variables)
Code Block | ||
---|---|---|
| ||
:global funcA do={ :return 5 } :global funcB do={ |
...
:global funcA; |
...
:return ([$funcA] + 4) } :put [$funcB] |
...
Output: 9 |
...
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 www.example.com]; :put "lala";} failure: dns name does not exist
Now we want to catch this error and proceed with our script:
Code Block | ||
---|---|---|
| ||
:do { |
...
|
...
:put [:resolve www.example.com]; } on-error={ :put "resolver failed"}; :put "lala" output: resolver failed lala |
...
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:
Code Block | ||
---|---|---|
| ||
[admin@ce0] > {:local a { "aX"=1 ; ay=2 }; :put ($a->"aX")} |
...
1 |
...
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 If the "foreach" command is used with one argument, then the element value will be returned:be returned:
Code Block | ||
---|---|---|
| ||
[admin@ce0] > :foreach k in={2; "aX"=1 ; y=2; 5} do={:put ("$k")} 2 5 1 2 |
...
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 executing
...
- a run command or in winbox
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: ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon) | list of applicable policies:
|
|
Read more detailed policy descriptions here | |
source (string;) | Script source code |
Read-only status properties:
Property | Description |
---|---|
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
Command | Description |
---|---|
run (run [id|name]) | Execute the specified script by ID or name |
Environment
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 "example"=123
Read-only status properties:
Property | Description |
---|---|
name (string) | Variable name |
user (string) |
The user who defined variable |
value () |
The value assigned to a variable |
Job
Sub-menu level: /system script job
Contains a list of all currently running scripts.
Read-only status properties:
Property | Description |
---|---|
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
...
Code Block | ||
---|---|---|
| ||