Scripting gives the administrator a way to execute console commands by writing a script for the router which is executed on the basis of time or events that can be monitored on the router. Some examples of uses of scripting could be: setting bandwidth settings according to time. In RouterOS v2.4, a script may be started in three ways. A script may be started according to a specific time or an interval of time. A script may also be started on an event - for example, if the netwatch tool sees that an address does not respond to pings. Also, a script may be started by another script.
To write a script, the writer must learn all of the console commands described in the relevant documentation. Scripts may be written for the System Scheduler, the Traffic Monitoring Tool, and for the Netwatch Tool.
The sheduler is used to execute scripts at certain times. It has an ordered list of scripts; each script has following properties:
Descriptions of settings:
name - useful for disabling or changing properties of this item from other scripts
start-time and start-date - time and date of first execution
interval - interval between two script executions, if time "interval" is set to zero, the script is only executed at it's start time, otherwise it is executed repeatedly at the time interval specified
run-count - to monitor script usage, this counter is incremented each time the script is executed, it can be reset to zero.
script - the script itself
Here is a simple script that logs "kuku" every hour sharp:
[mountain] system scheduler> add name=x interval=1h script={:log message=kuku}
[mountain] system scheduler> print
Flags: X - disabled
0 name=x start-time=00:00:00 start-date=jan/01/1970 interval=1h run-count=0
script=:log message=kuku
[mountain] system scheduler>
Here are two scripts that will change the bandwidth setting of a queue rule. Everyday at 9AM the queue will be set to 64Kb/s and at 5PM the queue will be set to 128Kb/s.
/system scheduler add interval=24h name="set-64k" start-time=9:00:00 script={
/ip queue set [/ip queue find dst-address=1.2.3.0/24:0-65535]
limit-at=64000
}
/system scheduler add interval=24h name="set-128k" start-time=21:00:00 script={
/ip queue set [/ip queue find dst-address=1.2.3.0/24:0-65535]
limit-at=128000
}
The following console command schedules script that sends each week backup of router configuration by e-mail.
/system scheduler add interval=7d name="email-backup" script={
/system backup save name=email
/e-mail send to="madmin@1.2.3.4" \
subject=[/system identity get name]" backup" \
file=email.backup
}
If more than one script has to be executed at one time, they are executed in the order they appear in the scheduler configuration. This can be important if, for example, one scheduled script is used to disable another. The order of scripts can be changed with "move" command.
If a more complex execution pattern is needed, it can usually be done by scheduling several scripts, and making them enable and disable each other. Example below will put 'x' in logs each hour from midnight till noon:
[mountain] system scheduler> print
Flags: X - disabled
0 name=x-up start-time=00:00:00 start-date=jan/01/1970 interval=24h
run-count=1 script=/system scheduler enable x
1 X name=x start-time=00:00:00 start-date=jan/01/1970 interval=1h run-count=3
script=:log message=x
2 name=x-down start-time=12:00:00 start-date=jan/01/1970 interval=24h
run-count=0 script=/system scheduler disable x
The traffic monitor tool is used to execute console scripts on when interface traffic crosses some given thresholds.
Each item in traffic monitor list consists of it's name (which is useful if you want to disable or change properties of this item from another script), some parameters specifying traffic condition and the script to execute when this condition is met.
[MikroTik] tool traffic-monitor> print
Flags: X - disabled, I - invalid
0 name=e2warm interface=ether2 threshold=15000 trigger=above
traffic=received script=...
1 name=e2cold interface=ether2 threshold=12000 trigger=below
traffic=transmitted script=...
Descriptions of arguments:
name - Name of traffic monitor item.
interface - Interface to monitor.
threshold - Traffic threshold, in bits per second.
trigger - ( above / always / below ) Condition on which to execute script.
traffic - ( transmitted / received ) Type of traffic to monitor.
script - Script source.
You should specify the interface on which to monitor the traffic, the type of traffic to monitor (transmitted or received), the threshold (bits per second). The script is started, when traffic exceeds the threshold in direction given by the "trigger" argument. "above" means that script will be run each time traffic exceeds the threshold, i.e. goes from being less than threshold to being more than threshold value. "below" triggers script in the opposite condition, when traffic drops under the threshold. "always" triggers script on both "above" and "below" conditions.
[MikroTik] tool traffic-monitor > add name=turn_on interface=ether1 threshold=15000\
script={/interface enable ether2} trigger=above traffic=received
[MikroTik] tool traffic-monitor > add name=turn_off interface=ether1 threshold=12000\
script={/interface disable ether2} trigger=below traffic=received
The example monitor enables the interface ether2, if the received traffic exceeds 15kbps on ether1, and disables the interface ether2, if the received traffic falls below 12kbps on ether1.
Netwatch monitors state of hosts on the network. It does so by sending ICMP pings to list of specified IP addresses. For each entry in netwatch table you can specify IP address, ping interval and console scripts. Here's an example configuration.
[bainug] tool netwatch> print Flags: X - disabled # HOST TIMEOUT INTERVAL STATUS 0 X 10.0.0.17 998ms 2s unknown
Scripts are not displayed by default, to see them type "detail" after "print" command.
[bainug] tool netwatch> print detail
Flags: X - disabled
0 X host=10.0.0.17 timeout=998ms interval=10s since=apr/1/2001 13:38:54
status=unknown up-script=/ip route set [/ip route find dst \
0.0.0.0] gateway 10.0.0.17
down-script=/ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.255
This line (when enabled) will ping 10.0.0.17 every 10 seconds, and if nothing comes back, it will change status to "down". If some pings do return, status will change to "up".
Without scripts, netwatch can be used just as an information tool, to see which links are up, or which specific host are running at the moment. The "since" field shows last time when state of host has changed.
The main advantage of netwatch is ability to issue arbitrary console commands on host state changes. Let's look at the example above - it changes default route if gateway becomes unreachable. How it's done?
There are two scripts. The "up-script" is executed once when status of host changes to "up". In our case, it's equivalent to entering this console command:
[bainug] tool netwatch> /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.17
The "/ip route find dst 0.0.0.0" command returns list of all routes whose "dst-address" value is zero. Usually that's the default route. It is substituted as first argument to "/ip route set" command, which changes gateway of this route to 10.0.0.17
The second script is executed once when status of host becomes "down". It does the following:
[bainug] tool netwatch> /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.255
ie. it restores default gateway if 10.0.0.17 address has become unreachable. Here's another example, that sends email notification whenever the 10.3.15.7 host goes down:
[avots] tool netwatch> print detail
Flags: X - disabled
0 host=10.3.15.7 timeout=999ms interval=20s since=sep/27/2001 13:55:04
status=up up-script=""
down-script=/e-mail send from="router@vieta.lv" server=\
"159.144.25.102" body="Router down" subject="Router at \
second floor is down" to="admin@vieta.lv"
Monitors hosts by pinging IP addresses. Following values can be configured for each list entry:
Descriptions of settings:
host - IP address of host that should be monitored
interval - Time between pings. Lowering this will make state changes more responsive, but can create unnecessary traffic and consume system resources.
timeout - Timeout for each ping. If no reply from host is received in this time, host is considered unreachable ("down").
up-script - Console script that is executed once when state of host changes from "unknown" or "down" to "up".
down-script - Console script that is executed once when state of host changes from "unknown" or "up" to "down".
In addition, following value is available with "print" command:
since - Time when state of host changed last time.
To see values of "up-script", "down-script" or "since" use "print detail" command form.
State of host changes to "unknown" when any properties of this list entry are changed, or it is enabled or disabled. Also, any entry that is added has state "unknown" initially.
Value of host IP address is available in both "up-script" and "down-script" scripts as value of variable "host". This variable is available only while the script is running, and it's values are not remembered or shared between multiple script executions.