Page History

...

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.

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 ]

31

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

MikroTik

:put [convert transform=lc "AAA"]

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

Code Block

language	ros

{
: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];

jobname

:jobname

return current script name

Code Block

language	ros
title	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!"]; $myFunc;

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

Code Block

language	ros

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

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"}
got error

Code Block

language	text

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

Specify

to specifies the format

using to=json.

Code Block

language	ros

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

deserialize

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

Deserialize specified value/array from JSON format. Specify the format using from=json.

Code Block

language	ros

:put [:deserialize from=json value="[\"a\",\"b\",\"c\"]"]
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 :timestamp returns the time since epoch, where epoch is January 1, 1970 (Thursday), not counting leap seconds

Code Block

language	text

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

toarray:toarray <var>convert a variable to the arraytobool:tobool <var>convert a variable to booleantoid:toid <var>convert a variable to internal IDtoip:toip <var>convert a variable to IP addresstoip6:toip6 <var>convert a variable to IPv6 addresstonum:tonum <var>convert a variable to an integertostr:tostr <var>convert a variable to a stringtotime:totime <var>convert a variable to time

Menu specific commands

Common commands

The following commands are available from most sub-menus:

...

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

...

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

Code Block

language	ros

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

: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") ]     
c;a;b
7;1;4
text;2;5
9;3;6

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.

Code Block

language	ros

:put [:deserialize from=json value="[\"a\",\"b\",\"c\"]"]
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

:timestamp

returns the time since epoch, where epoch is January 1, 1970 (Thursday), not counting leap seconds

Code Block

language	text

[admin@MikroTik] > :put [:timestamp]
2735w21:41:43.481891543
or
[admin@MikroTik] > :put [:timestamp]
2735w1d21:41:43.481891543
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:

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: `/ip firewall filter add chain=blah action=accept protocol=tcp port=123 nth=4,2 print set 0 !port chain=blah2 !nth protocol=udp`
get	`get <id> <param>=<value>`	get the selected item's parameter value
print	`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.

Starting from 7.16.x version, its possible to catch syntax errors:

Code Block

language	ros

[admin@admin] > do { import test.rsc } on-error={ :put "Failure" }  
Failure

New parameter onerror can be used:

Code Block

language	ros

[admin@admin] > onerror e in={ import test.rsc } do={ :put "Failure - $e" }       
Failure - Script Error: bad command name this (line 1 column 1)

In addition, the import command has new options in verbose mode - the dry-run parameter is specially designed for debugging and can find multiple errors without changing the configuration.

Code Block

language	ros

[admin@admin] > import test.rsc verbose=yes dry-run 
#line 1
this
bad command name this (line 1 column 1)
...
Script Error: found 5 error(s) in import file

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:

...

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 using user permissions.
use-script-permissions	Additional parameter to execute script using script permissions.

Environment

Sub-menu level:

...

Page tree

Versions Compared

Old Version 60

New Version Current

Key

Menu specific commands

Common commands

Menu specific commands

Common commands

import

import

print parameters

Environment