Scripting

RouterOS bevat een krachtige scripttaal voor het automatiseren van onderhoudstaken. U maakt door de gebruiker gedefinieerde scripts en koppelt deze aan gebeurtenissen.

Je kunt scripts opslaan in de Script-repository of ze rechtstreeks in de CLI schrijven. Veelvoorkomende triggers zijn onder meer de System Scheduler, de Traffic Monitoring Tool en gebeurtenissen van de Netwatch Tool.

Als u al bekend bent met scripting in RouterOS, wilt u misschien onze Tips & Tricks bekijken.

Regelstructuur

Het RouterOS-script is opgedeeld in een aantal commandoregels. De commandoregels worden een voor een uitgevoerd tot het einde van het script of totdat er een runtime-fout optreedt.

Command-line

De RouterOS CLI gebruikt de volgende commandosyntaxis:

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

• [prefix] - het teken : of / geeft aan of het volgende word een global command of een pad is. Een prefix is niet vereist wanneer het wordt aangeroepen vanuit het rootmenu of vanuit het menu dat relatief is aan het aangeroepen pad/commando.
• [path] - relatief pad naar het gewenste menuniveau. Het is mogelijk niet vereist.
• command - een van de commando's die beschikbaar zijn op het opgegeven menuniveau.
• [uparam] - naamloze parameter, moet worden opgegeven als het commando dit vereist.
• [params] - een reeks benoemde parameters gevolgd door waarden (als een parameter een waarde vereist).

Het einde van de commandoregel wordt weergegeven door het token ; of NEWLINE. Een commando dat is omsloten door (), [] of {} vereist geen einde-van-commando teken. Het einde van het commando wordt bepaald door de inhoud van het gehele script

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

Elke commandoregel binnen een andere commandoregel begint en eindigt met vierkante haken [] (operator voor het samenvoegen van commando's).

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

Merk op dat de bovenstaande code drie commandoregels bevat:

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

Merk op dat het menuspecifieke commando find geen volledig pad vereist, omdat het pad wordt afgeleid van het pad van het bovenliggende commando.

Een commandoregel kan uit meer dan één fysieke regel worden opgebouwd door de regels voor regelsamenvoeging te volgen.

Fysieke lijn

Een fysieke regel is een reeks tekens die wordt afgesloten door een end-of-line (EOL)-reeks. Elk van de standaard regelafsluitingsreeksen van het platform kan worden gebruikt:

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

De standaard C-conventies voor newline-tekens kunnen worden gebruikt ( \n, \r\n tekens).

Comments

De volgende regels gelden voor een commentaar:

• Een commentaar begint met een hekje # en eindigt aan het einde van de fysieke regel.
• RouterOS ondersteunt geen commentaar over meerdere regels.
• Als er een # teken in de string voorkomt, wordt dit niet als commentaar beschouwd.

# this is a comment
# continued comment in the next line
:global a; # comment describing variable

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

Regels samenvoegen

Twee of meer fysieke regels kunnen tot logische regels worden samengevoegd met het backslash-teken (\). De volgende regels gelden voor het gebruik van de backslash als hulpmiddel om regels samen te voegen:

• Een regel die eindigt op een backslash kan geen commentaar bevatten.
• Een backslash zet een commentaar niet voort.
• Een backslash zet een token niet voort, behalve bij stringliteralen.
• Een backslash is elders op een regel buiten een stringliteraal niet toegestaan.

:if ($a = true \
	and $b=false) do={ :put "$a $b"; }
:if ($a = true \ # bad comment (syntax error)
	and $b=false) do={ :put "$a $b"; }
# comment \
	continued is invalid (syntax error)

Witruimte tussen tokens

Witruimte kan gebruikt worden om tokens te scheiden. Witruimte tussen twee tokens is alleen nodig als hun samenvoeging als een ander token geïnterpreteerd zou kunnen worden. Voorbeeld:

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

Witruimtetekens zijn niet toegestaan:

• tussen <parameter>=.
• tussen from=, to=, step=, in=, do=, else=.

Voorbeeld:

#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

Variabelen kunnen alleen worden gebruikt in bepaalde delen van het script, scopes genoemd. Deze delen bepalen de zichtbaarheid van de variabele. Een variabele die binnen een blok wordt gedeclareerd, is alleen toegankelijk binnen dat blok en de geneste blokken daarvan, en alleen na het punt van declaratie.

Er zijn twee typen scopes: global en local.

Globale scope

De globale scope of root-scope is de standaardscope van het script. Deze wordt automatisch aangemaakt en kan niet worden uitgeschakeld.

Een globale variabele die door een ander script is ingesteld, kan worden benaderd door deze te declareren zonder er een waarde aan toe te kennen.

Het eerste script stelt bijvoorbeeld de waarde van myVar in op 3:

:global myVar 3

Om deze variabele vanuit een ander script te benaderen:

:global myVar
:put "myVar=$myVar"

Uitvoer:

myVar=3

Lokale scope

Je kunt groepen definiëren om de toegang tot variabelen te beperken; deze worden lokale scopes genoemd. Elke lokale scope wordt omsloten door accolades ({}).

{  
    :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 this scope  
    :put ($a+$b);
}

Variabele b is in een lokale scope gedeclareerd en is niet toegankelijk na de sluitende accolade.

Elke regel die in de CLI wordt geschreven, wordt behandeld als een lokale scope. Zo is een gedefinieerde lokale variabele niet zichtbaar in de volgende commandoregel en genereert deze een syntaxisfout

[admin@MikroTik] > :local myVar a;
[admin@MikroTik] > :put $myVar
syntax error (line 1 column 7)

Gevaar Definieer geen global-variabele binnen een local-scope.

Ook als een variabele als global gedefinieerd kan worden, is deze alleen vanuit zijn eigen scope beschikbaar, tenzij ernaar wordt verwezen om buiten de scope zichtbaar te zijn.

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

De code geeft 3 als uitvoer omdat b buiten de scope niet zichtbaar is.

De volgende code lost het probleem op en geeft zoals bedoeld 7 als uitvoer:

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

Keywords

De volgende woorden zijn sleutelwoorden en kunnen niet gebruikt worden als namen voor variabelen en functies:

and       or       in

Delimiters

De volgende tokens dienen als scheidingstekens in de grammatica:

()  []  {}  :   ;   $   /

Datatypen

De RouterOS-scripttaal heeft de volgende datatypen:

Constante escape-reeksen

De volgende escapesequenties kunnen worden gebruikt om bepaalde speciale tekens binnen een string te definiëren:

Bijvoorbeeld:

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

geeft als uitvoer:

HELLO
This
is
a
test

Operators

Rekenkundige operatoren

In de RouterOS-scripttaal worden de gebruikelijke rekenkundige operatoren ondersteund:

Merk op dat u voor de deling haakjes of spaties rond het deeltal moet gebruiken, zodat het niet ten onrechte als een IP-adres wordt gezien.

Relationele operatoren

Om een expressie te ontkennen, kunt u <expression>=false gebruiken. Om bijvoorbeeld alle interfaces af te drukken die geen "ethernet" zijn, kunt u expressie-negatie zo gebruiken:

/interface/print where (name~"ether")=false

Of om het tegenovergestelde te doen, kunt u <expression>=true gebruiken:

/interface/print where (name~"ether")=true

Logische operatoren

Bitwise Operators

Bitwise operators werken alleen op de datatypes IP en IPv6-adres.

Bereken bijvoorbeeld een subnetadres uit een gegeven IP en CIDR-netmask met de operator &:

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

Haal de laatste 8 bits op uit de opgegeven IP-adressen:

 :put (192.168.88.77&0.0.0.255);

Gebruik de operator | en een omgekeerd CIDR-masker om het broadcastadres te berekenen:

{
:local IP 192.168.88.77;
:local Network 192.168.88.0;
:local CIDRnetmask 255.255.255.0;
:local InvertedCIDR (~$CIDRnetmask);
:put ($Network|$InvertedCIDR)
}

Concatenatie-operatoren

Het is mogelijk om variabelewaarden rechtstreeks aan strings toe te voegen zonder een concatenatie-operator:

:global myVar "world";

# value can be added with concatenation operator
:put ("Hello " . $myVar);
# or without operator
:put "Hello $myVar";

Met $[] en $() kunt u expressies uitvoeren en de resulterende waarde in strings invoegen:

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

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

Andere operatoren

Variables

De scripttaal kent twee soorten variabelen:

• global - Toegankelijk vanuit alle scripts die door de huidige gebruiker zijn gemaakt, gedefinieerd met het sleutelwoord global.
• local - Alleen toegankelijk binnen de huidige scope, gedefinieerd met het sleutelwoord local.

Variabelen kunnen ongedefinieerd zijn. Wanneer dat gebeurt, zoekt de parser naar ingebouwde variabelen die door de applicatie worden aangeleverd. Zo levert het DHCP lease-script bijvoorbeeld verschillende ingebouwde variabelen:

/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

Behalve de ingebouwde RouterOS-variabelen moet elke variabele vóór gebruik worden gedeclareerd met het sleutelwoord local of global. Het gebruik van een niet-gedeclareerde variabele resulteert in een compilatiefout. Bijvoorbeeld:

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

Correcte code:

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

Geldige tekens in variabelenamen zijn letters en cijfers. Als een variabelenaam een ander teken dan letters of cijfers bevat (inclusief operatoren), plaats deze dan tussen dubbele aanhalingstekens (""). Voorbeeld:

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

Als een variabele eerst zonder waarde wordt gedefinieerd, wordt het datatype van de variabele ingesteld op nil; anders bepaalt de scripting-engine het datatype automatisch. Soms is conversie van het ene datatype naar het andere nodig. Dit kan worden bereikt met dataconversiecommando's. Voorbeeld:

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

Variabelenamen zijn hoofdlettergevoelig.

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

Het commando set zonder waarde maakt een variabele ongedefinieerd:

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

Gereserveerde variabelenamen

Alle ingebouwde RouterOS-eigenschappen zijn gereserveerde variabelen. Variabelen die met dezelfde namen als ingebouwde RouterOS-eigenschappen zijn gedefinieerd, kunnen fouten veroorzaken. Kies andere namen om dit te voorkomen.

Het volgende script werkt bijvoorbeeld niet:

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

Maar het werkt wel met andere gedefinieerde variabelen:

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

Commands

Globale commando's

Elk globaal commando moet beginnen met het token :; anders wordt het als een variabele behandeld.

Als een functie voor het converteren van een variabeletype het nieuwe formaat niet op de aangeleverde data kan toepassen, is de uitvoer leeg.

Als u bijvoorbeeld het commando :tonum <var> uitvoert op een variabele met een niet-gehele waarde zoals "23.8" of "cow&chicken", is het resultaat leeg en wordt het datatype getoond als nil.

Veelgebruikte commando's

De volgende commando's zijn beschikbaar vanuit de meeste submenu's:

import

Het import-commando is beschikbaar vanuit het hoofdmenu en wordt gebruikt om configuratie te importeren uit bestanden die zijn aangemaakt met een export commando of handmatig zijn geschreven.

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

De parameter onerror kan worden gebruikt om de fouten op te vangen:

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

Daarnaast heeft het commando import nieuwe opties in de verbose-modus: de parameter dry-run is bedoeld voor debuggen en kan worden gebruikt om fouten te vinden zonder de configuratie te wijzigen.

[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

print-parameters

Er zijn verschillende algemene parameters beschikbaar voor het print commando:

Er kan meer dan één parameter tegelijk worden opgegeven, bijvoorbeeld /ip route print count-only interval=1 where interface="ether1"

Lussen en voorwaardelijke statements

Loops

Voorwaardelijke instructie

Voorbeeld:

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

Functions

Functies worden op vergelijkbare wijze gedefinieerd als globale variabelen, met het sleutelwoord global gevolgd door de operator do=, waarna de body tussen accolades ({}) staat.

Er zijn twee manieren om argumenten door te geven:

• Geef arg met een specifieke naam door.
• Geef de waarde door zonder arg-naam; in dat geval wordt arg "1", "2" .. "n" gebruikt om naar de waarde te verwijzen.

#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

Je kunt een functiewaarde teruggeven met het commando :return.

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

output:
8

Je kunt zelfs een bestaand script uit de scriptomgeving klonen en het als functie gebruiken.

#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 !

De scripttaal maakt het ook mogelijk indirect functies te maken door middel van het commando :parse.

Als de functie een gedefinieerde globale variabele bevat waarvan de naam overeenkomt met de naam van de doorgegeven parameter, wordt de globaal gedefinieerde variabele genegeerd, voor compatibiliteit met scripts die voor oudere versies zijn geschreven. Vermijd het gebruik van parameters met dezelfde naam als globale variabelen.

Bijvoorbeeld:

:global my2 "123"

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

De uitvoer zal zijn:

1234
lala
global value 123

Om een functie vanuit een andere functie aan te roepen (een geneste functie), declareert u de naam ervan zoals u dat bij een variabele zou doen:

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

Output:
9

Runtime-fouten opvangen

RouterOS-scripting maakt het mogelijk runtime-fouten op te vangen die anders het script onverwacht zouden beëindigen. Het commando :resolve genereert bijvoorbeeld een fout en breekt het script af als het mislukt.

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

Je kunt deze fout opvangen en verdergaan met het script:

:onerror e {:put [:resolve www.example.com]} do={:put "resolver failed"}
:put "print after failure"

output:

resolver failed
print after failure

Bewerkingen met arrays

Als een sleutelnaam in een array een ander teken dan een kleine letter bevat, moet deze tussen aanhalingstekens worden gezet. Bijvoorbeeld:

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

foreach commando kan worden gebruikt om door sleutels en elementen te lopen:

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

0=2
1=5
aX=1
y=2

Als het foreach commando met één argument wordt aangeroepen, geeft het de elementwaarde terug:

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

2
5
1
2

Als een array-element een sleutel heeft, worden die elementen alfabetisch gesorteerd; elementen zonder sleutel worden vóór elementen met sleutel geplaatst en behouden hun volgorde (zoals geïllustreerd in het vorige voorbeeld).

Het is mogelijk om de waarde van een enkel element te wijzigen met behulp van de sleutelnaam:

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

Scriptrechten

Afhankelijk van hoe een script wordt aangeroepen, kan het:

• Gebruik zijn eigen rechten.
• Neem de rechten van de aanroeper over.

Denk bijvoorbeeld aan een gebruiker met volledige rechten en een script waarvoor geen rechten zijn ingesteld:

/user/print
Columns: NAME, GROUP, LAST-LOGGED-IN, INACTIVITY-POLICY
# NAME   GROUP  LAST-LOGGED-IN       INACTIVITY-POLICY
;;; system default user
0 admin  full   2025-07-22 17:09:59  none

/system script
add dont-require-permissions=no name=add-dhcp-no-perms owner=admin policy="" sour
ce="/ip dhcp-client add interface=ether2; put \"Added DHCP client on ether2!\""

Laten we kijken wat er gebeurt als we het script uitvoeren met en zonder de parameter use-script-permissions:

[admin@MikroTik] > system/script/run add-dhcp-no-perms  use-script-permissions
not enough permissions (9)
[admin@MikroTik] > system/script/run add-dhcp-no-perms
Added DHCP client on ether2!

Op vergelijkbare wijze zijn er meerdere manieren om een script met de scheduler uit te voeren. Wanneer de scheduler een script uitvoert, kan dit gebeuren met de rechten van de scheduler.

Je kunt het script op naam aanroepen met de scheduler; dit werkt op dezelfde manier als /system script run use-script-permissions.

Om dit te demonstreren maken we drie schedulers aan, die elk zo zijn geconfigureerd dat ze het script op een andere manier uitvoeren:

/system scheduler
add interval=10s name=run-script-use-script-perms on-event="/system script run add-dhcp-no-perms use-script-permissions" policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon
add interval=10s name=run-script-direct on-event=add-dhcp-no-perms policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon
add interval=10s name=run-script-scheduler-perms on-event="/system script run add-dhcp-no-perms" policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive,romon

Wanneer alle aangemaakte schedulers het script uitvoeren, laten de logs zien dat de twee methoden met use-script-permissions of het aanroepen van het script bij naam mislukken vanwege onvoldoende rechten.

Daarentegen voert run-script-scheduler-perms het script wel met succes uit, omdat het de rechten van de scheduler erft.

/log print
 2025-07-22 18:11:25 script,error executing script add-dhcp-no-perms from scheduler (run-script-direct) failed, please check it manually
 2025-07-22 18:11:25 script,error,debug not enough permissions (9) (/ip/dhcp-client/add; line 1)
 2025-07-22 18:11:25 script,error executing script from scheduler (run-script-use-script-perms) failed, please check it manually
 2025-07-22 18:11:25 script,error,debug (scheduler:run-script-use-script-perms) not enough permissions (9) (/ip/dhcp-client/add; line 1)
 2025-07-22 18:11:25 system,info dhcp client added by scheduler:run-script-scheduler-perms/script:add-dhcp-no-perms (*7 = /ip dhcp-client add interface=ether2)

Een script met hogere of meer rechten dan de gebruiker/scheduler kan niet worden uitgevoerd; use-script-permissions doet daar niets aan af.

Zie ook

• Scriptingvoorbeelden
• Scripting tips en trucs