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 scripts are stored under '/system script'. Use the 'add' command to add a new script. The following example is a script for writing message "kuku" to the system log:
[MikroTik] system script> add name=log-test source={:log message=kuku}
[MikroTik] system script> print
0 name=log-test source=:log message=kuku owner=admin run-count=0
[MikroTik] system script>
Argument description:
name - name of the script to be referenced when invoking it. If not specified, the name is generated automatically as "scriptX", X=1,2,...
source - the script itself
owner - user's name who created the script
run-count - usage counter. This counter is incremented each time the script is executed, it can be reset to zero by setting 'run-counter=0'
last-started - date and time when the script has been last invoked. The argument is shown only if the 'run-count=0'.
You can execute a script by using the 'run' command.
To manage the active or scheduled tasks, use the '/system script job' menu. You can see the status of all currently active tasks using the 'print' command. For example, we have a script that delays some process for 10 minutes:
[MikroTik] system script> add name=DelayeD source={:delay 10m}
[MikroTik] system script> print
0 name=log-test source=:log message=kuku owner=admin
last-started=may/09/2001 03:22:19 run-count=1
1 name=DelayeD source=:delay 10m owner=admin run-count=0
[MikroTik] system script> run DelayeD
[MikroTik] system script> job print
# SCRIPT STARTED
0 DelayeD may/09/2001 03:32:18
[MikroTik] system script>
You can cancel execution of a script by removing it from the jobs list:
[MikroTik] system script> job remove 0
[MikroTik] system script> job print
[MikroTik] system script> print
0 name=log-test source=:log message=kuku owner=admin
last-started=may/09/2001 03:36:44 run-count=3
1 name=DelayeD source=:delay 10m owner=admin
last-started=may/09/2001 03:32:18 run-count=1
[MikroTik] system script>
The scheduler is used to execute scripts at certain times. It has an ordered list of tasks. To add a task, use the 'add' command. For example, we add a task that executes the script 'log-test' every hour:
[MikroTik] system scheduler> add name=run-1h interval=1h script=log-test
[MikroTik] system scheduler> print
Flags: X - disabled
# NAME SCRIPT START-DATE START-TIME INTERVAL RUN-COUNT
0 run-1h log-test may/09/2001 03:45:02 1h 1
[MikroTik] system scheduler> .. script print
0 name=log-test source=:log message=kuku owner=admin
last-started=may/09/2001 03:45:02 run-count=4
[MikroTik] system scheduler>
Argument description:
name - name of the task
delay - delay time before starting the task after it has been added. Should be used instead of start-time and start-date.
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 - name of the script. The script must be present at '/system script'.
Here are two scripts that will change the bandwidth setting of a queue rule "Cust0". Everyday at 9AM the queue will be set to 64Kb/s and at 5PM the queue will be set to 128Kb/s. The queue rule, the scripts, and the scheduler tasks are below:
[MikroTik] queue simple>
add name=Cust0 interface=Local dst-address=192.168.0.0/24 limit-at=64000
[MikroTik] queue simple> print
Flags: X - disabled, I - invalid
0 name=Cust0 src-address=0.0.0.0/0 dst-address=192.168.0.0/24
interface=Local limit-at=64000 queue=default priority=8 bounded=yes
[MikroTik] queue simple> /system script
[MikroTik] system script>
add name=start_limit source={/queue simple set Cust0 limit-at=64000}
add name=stop_limit source={/queue simple set Cust0 limit-at=128000}
[MikroTik] system script> print
0 name=start_limit source=/queue simple set Cust0 limit-at=64000
owner=admin run-count=0
1 name=stop_limit source=/queue simple set Cust0 limit-at=128000
owner=admin run-count=0
[MikroTik] system script> .. scheduler
[MikroTik] system scheduler>
add interval=24h name="set-64k" start-time=9:00:00 script=start_limit
add interval=24h name="set-128k" start-time=17:00:00 script=stop_limit
[MikroTik] system scheduler> print
Flags: X - disabled
# NAME SCRIPT START-DATE START-TIME INTERVAL RUN-COUNT
0 set-64k start... may/09/2001 09:00:00 1d 0
1 set-128k stop_... may/09/2001 17:00:00 1d 0
[MikroTik] system scheduler>
The following setup schedules script that sends each week backup of router configuration by e-mail.
[MikroTik] system script>
add name=e-backup source={/system backup save name=email;
/tool e-mail send to="root@host.com" \
subject=[/system identity get name]" Backup" \
file=email.backup}
[MikroTik] system script> .. scheduler
[MikroTik] system scheduler>
add interval=7d name="email-backup" script=e-backup
[MikroTik] system scheduler> print
Flags: X - disabled
# NAME SCRIPT START-DATE START-TIME INTERVAL RUN-COUNT
0 email-... e-backup mar/21/2002 19:12:53 7d 1
[MikroTik] system scheduler>
Do not forget to set the e-mail settings, i.e., the SMTP server and From: address under '/tool e-mail'. For example:
[MikroTik] tool e-mail>
set server=159.148.147.198 from=SysAdmin@host.com
[MikroTik] tool e-mail> print
server: 159.148.147.198
from: SysAdmin@host.com
[MikroTik] tool e-mail>
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 the "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:
[MikroTik] system script>
add name=enable-x source={/system scheduler enable x}
add name=disable-x source={/system scheduler disable x}
add name=log-x source={:log message=x}
[MikroTik] system script> .. scheduler
[MikroTik] system scheduler>
add name=x-up start-time=00:00:00 interval=24h script=enable-x
add name=x-down start-time=12:00:00 interval=24h script=disable-x
add name=x start-time=00:00:00 interval=1h script=log-x
[MikroTik] system scheduler> print
Flags: X - disabled
# NAME SCRIPT START-DATE START-TIME INTERVAL RUN-COUNT
0 x-up enable-x mar/22/2002 00:00:00 1d 0
1 x-down disab... mar/22/2002 12:00:00 1d 0
2 x log-x mar/22/2002 00:00:00 1h 0
[MikroTik] system scheduler>
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 its 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 pointer to a script or scheduled event to execute when this condition is met.
Argument description for traffic monitoring tool:
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.
on-event - Script source. Must be present under '/system script'.
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.
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.
[MikroTik] system script>
add name=eth-up source={/interface enable ether2}
add name=eth-down source={/interface disable ether2}
[MikroTik] system script> /tool traffic-monitor
[MikroTik] tool traffic-monitor>
add name=turn_on interface=ether1 on-event=eth-up \
threshold=15000 trigger=above traffic=received
add name=turn_off interface=ether1 on-event=eth-down \
threshold=12000 trigger=below traffic=received
[MikroTik] tool traffic-monitor> print
Flags: X - disabled, I - invalid
# NAME INTERFACE TRAFFIC TRIGGER THRESHOLD ON-EVENT
0 turn_on ether1 received above 15000 eth-up
1 turn_off ether1 received below 12000 eth-down
[MikroTik] tool traffic-monitor>
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.
The main advantage of netwatch is ability to issue arbitrary console commands on host state changes. Here's an example configuration of netwatch. It will run the scripts gw_1 or gw_2 which change the default gateway depending on the status of one of the gateways:
[MikroTik] system script>
add name=gw_1 source={/ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.1}
add name=gw_2 source={/ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.217}
[MikroTik] system script> /tool netwatch
add host=10.0.0.217 interval=10s timeout=998ms up-script=gw_2 down-script=gw_1
[MikroTik] tool netwatch> print
Flags: X - disabled
# HOST TIMEOUT INTERVAL STATUS
0 10.0.0.217 997ms 10s up
[MikroTik] tool netwatch> print detail
Flags: X - disabled
0 host=10.0.0.217 timeout=997ms interval=10s since=mar/22/2002 11:21:03
status=up up-script=gw_2 down-script=gw_1
[MikroTik] tool netwatch>
Argument description:
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".
since - Time when state of host changed last time.
status - tells the current status of the host (up / down / unknown). 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.
Hint: Scripts are not printed by default, to see them, type 'print detail'.
Without scripts, netwatch can be used just as an information tool to see which links are up, or which specific hosts are running at the moment.
Let's look at the example above - it changes default route if gateway becomes unreachable. How it's done? There are two scripts. The script "gw_2" is executed once when status of host changes to "up". In our case, it's equivalent to entering this console command:
[MikroTik] > /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.217
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.217
The script "gw_1" is executed once when status of host becomes "down". It does the following:
[MikroTik] > /ip route set [/ip route find dst 0.0.0.0] gateway 10.0.0.1
It changes the default gateway if 10.0.0.217 address has become unreachable.
Here's another example, that sends email notification whenever the 10.0.0.215 host goes down:
[MikroTik] system script>
add name=e-down source={/tool e-mail send from="rieks@mt.lv" server=\
"159.148.147.198" body="Router down" subject="Router at \
second floor is down" to="rieks@latnet.lv"}
add name=e-up source={/tool e-mail send from="rieks@mt.lv" server=\
"159.148.147.198" body="Router up" subject="Router at \
second floor is up" to="rieks@latnet.lv"}
[MikroTik] system script>
[MikroTik] system script> /tool netwatch
[MikroTik] system script>
add host=10.0.0.215 timeout=999ms interval=20s \
up-script=e-up down-script=e-up
[MikroTik] tool netwatch> print detail
Flags: X - disabled
0 host=10.0.0.215 timeout=998ms interval=20s since=mar/22/2002 14:07:36
status=up up-script=e-up down-script=e-up
[MikroTik] tool netwatch>