Bahasa Indonesia

Virtual Router Redundancy Protocol (VRRP) implementation in the MikroTik RouterOS is RFC2338 compliant. VRRP protocol is used to ensure constant access to some resources. Two or more routers (referred as VRRP Routers in this context) create a highly available cluster (also referred as Virtual routers) with dynamic fail over. Each router can participate in not more than 255 virtual routers per interface. Many modern routers support this protocol.

Network setups with VRRP clusters provide high availability for routers without using clumsy ping-based scripts.

Specifications

Packages required: system
License required: Level1
Submenu level: /ip vrrp
Standards and Technologies: VRRP, AH, HMAC-MD5-96 within ESP and AH
Hardware usage: Not significant

Related Documents

Description

Virtual Router Redundancy Protocol is an election protocol that provides high availability for routers. A number of routers may participate in one or more virtual routers. One or more IP addresses may be assigned to a virtual router. A node of a virtual router can be in one of the following states:

Notes

VRRP does not currently work on VLAN interfaces, as it is impossible to have the MAC address of a VLAN interface different from the MAC address of the physical interface it is put on.

VRRP Routers

Submenu level: /ip vrrp

Description

A number of VRRP routers may form a virtual router. The maximal number of clusters on one network is 255 each having a unique VRID (Virtual Router ID). Each router participating in a VRRP cluster must have it priority set to a valid value.

Property Description

authentication (none | simple | ah; default: none) – authentication method to use for VRRP advertisement packets

interface (name) – interface name the instance is running oninterval (integer: 1..255; default: 1) – VRRP update interval in seconds. Defines how frequently the master of the given cluster sends VRRP advertisement packetsname (name) – assigned name of the VRRP instanceon-backup (name; default: “”) – script to execute when the node switch to backup stateon-master (name; default: “”) – script to execute when the node switch to master statepassword (text; default: “”) – password required for authentication depending on method used can be ignored (if no authentication used), 8-character long text string (for plain-text authentication) or 16-character long text string (128-bit key required for AH authentication)preemption-mode (yes | no; default: yes) – whether preemption mode is enabled

priority (integer: 1..255; default: 100) – priority of the current node (higher values mean higher priority)

vrid (integer: 0..255; default: 1) – Virtual Router Identifier (must be unique on one interface)

Notes

All the nodes of one cluster must have the same vrid, interval, preemption-mode, authentication and password.

As said before, priority of 255 is reserved for the real owner of the virtual router’s IP addresses. Theoretically, the owner should have the IP address added statically to its IP address list and also to the VRRP virtual address list, but you should never do this! Any addresses that you are using as virtual addresses (i.e. they are added in /ip vrrp address) must not appear in /ip address list as they otherwise can cause IP address conflict, which will not be resolved automatically.

Also You must have an IP address (no matter what) on the interface you want to run VRRP on.

To add a VRRP instance on ether1 interface, forming (because priority is 255) a virtual router with vrid of 1:

[admin@MikroTik] ip vrrp> add interface=ether1 vrid=1 priority=255
[admin@MikroTik] ip vrrp> print
Flags: X - disabled, I - invalid, M - master, B - backup
  0  I  name="vr1" interface=ether1 vrid=1 priority=255 interval=1
        preemption-mode=yes authentication=none password="" on-backup=""
        on-master=""

[admin@MikroTik] ip vrrp>

Virtual IP addresses

Submenu level: /ip vrrp address

Property Description

address (IP address) – IP address belongs to the virtual routerbroadcast (IP address) – broadcasting IP addressinterface (name; default: default) – interface, where to put the address on (may be different form the interface this VRRP instance is running on)

network (IP address) – IP address of the networkvirtual-router (name) – VRRP router’s name the address belongs to

Notes

The virtual IP addresses should be the same for each node of a virtual router.

To add a virtual address of 192.168.1.1/24 to the vr1 VRRP router:

[admin@MikroTik] ip vrrp> address add address=192.168.1.1/24 \
\... virtual-router=vr1
[admin@MikroTik] ip vrrp> address print
Flags: X - disabled, A - active
 #    ADDRESS            NETWORK         BROADCAST       INSTANCE INTERFACE
 0    192.168.1.1/24     192.168.1.0     192.168.1.255   vr1      default

[admin@MikroTik] ip vrrp>

A simple example of VRRP fail over

Description

VRRP protocol may be used to make a redundant Internet connection with seamless fail-over. Let us assume that we have 192.168.1.0/24 network and we need to provide highly available Internet connection for it. This network should be NATted (to make fail-over with public IPs, use such dynamic routing protocols as BGP or OSPF together with VRRP). We have connections to two different Internet Service Providers (ISPs), and one of them is preferred (for example, it is cheaper or faster).

This example shows how to configure VRRP on the two routers shown on the diagram. The routers must have initial configuration: interfaces are enabled, each interface have appropriate IP address (note that each of the two interfaces should have an IP address), routing table is set correctly (it should have at least a default route). SRC-NAT or masquerading should also be configured before. See the respective manual chapters on how to make this configuration.

We will assume that the interface the 192.168.1.0/24 network is connected to is named local on both VRRP routers

Configuring Master VRRP router

First of all we should create a VRRP instance on this router. We will use the priority of 255 for this router as it should be preferred router.

[admin@MikroTik] ip vrrp> add interface=local priority=255
[admin@MikroTik] ip vrrp> print
Flags: X - disabled, I - invalid, M - master, B - backup
  0   M name="vr1" interface=local vrid=1 priority=255 interval=1
        preemption-mode=yes authentication=none password="" on-backup=""
        on-master=""

[admin@MikroTik] ip vrrp>

Next the virtual IP address should be added to this VRRP instance

[admin@MikroTik] ip vrrp> address add address=192.168.1.1/24 \
\... virtual-router=vr1
[admin@MikroTik] ip vrrp> address print
Flags: X - disabled, A - active
 #    ADDRESS            NETWORK         BROADCAST       INSTANCE INTERFACE
 0    192.168.1.1/24     192.168.1.0     192.168.1.255   vr1      default

[admin@MikroTik] ip vrrp>

Now this address should appear in /ip address list:

[admin@MikroTik] ip address> print
Flags: X - disabled, I - invalid, D - dynamic
  #   ADDRESS            NETWORK         BROADCAST       INTERFACE
  0   10.0.0.1/24        10.0.0.0        10.0.0.255      public
  1   192.168.1.2/24     192.168.1.0     192.168.1.255   local
  2 D 192.168.1.1/24     192.168.1.0     192.168.1.255   local

[admin@MikroTik] ip address>

Configuring Backup VRRP router

Now we will create VRRP instance with lower priority (we can use the default value of 100), so this router will back up the preferred one:

[admin@MikroTik] ip vrrp> add interface=local
[admin@MikroTik] ip vrrp> print
Flags: X - disabled, I - invalid, M - master, B - backup
  0   B name="vr1" interface=local vrid=1 priority=100 interval=1
        preemption-mode=yes authentication=none password="" on-backup=""
        on-master=""

[admin@MikroTik] ip vrrp>

Now we should add the same virtual address as was added to the master node:

[admin@MikroTik] ip vrrp> address add address=192.168.1.1/24 \
\... virtual-router=vr1
[admin@MikroTik] ip vrrp> address print
Flags: X - disabled, A - active
 #    ADDRESS            NETWORK         BROADCAST       INSTANCE INTERFACE
 0    192.168.1.1/24     192.168.1.0     192.168.1.255   vr1      default

[admin@MikroTik] ip vrrp>

Note that this address will not appear in /ip address list:

[admin@MikroTik] ip address> print
Flags: X - disabled, I - invalid, D - dynamic
  #   ADDRESS            NETWORK         BROADCAST       INTERFACE
  0   10.1.0.1/24        10.0.0.0        10.0.0.255      public
  1   192.168.1.3/24     192.168.1.0     192.168.1.255   local

[admin@MikroTik] ip address>

Testing fail over

Now, when we will disconnect the master router, the backup one will switch to the master state:

[admin@MikroTik] ip vrrp> print
Flags: X - disabled, I - invalid, M - master, B - backup
  0   M name="vr1" interface=local vrid=1 priority=100 interval=1
        preemption-mode=yes authentication=none password="" on-backup=""
        on-master=""

[admin@MikroTik] ip vrrp> /ip address print
Flags: X - disabled, I - invalid, D - dynamic
  #   ADDRESS            NETWORK         BROADCAST       INTERFACE
  0   10.1.0.1/24        10.0.0.0        10.0.0.255      public
  1   192.168.1.3/24     192.168.1.0     192.168.1.255   local
  2 D 192.168.1.1/24     192.168.1.0     192.168.1.255   local

[admin@MikroTik] ip vrrp>

©

Bahasa Indonesia

The UPS monitor feature works with APC UPS units that support “smart” signaling over serial RS232 or USB connection. This feature enables the network administrator to monitor the UPS and set the router to ‘gracefully’ handle any power outage with no corruption or damage to the router. The basic purpose of this feature is to ensure that the router will come back online after an extended power failure. To do this, the router will monitor the UPS and set itself to hibernate mode when the utility power is down and the UPS battery is has less than 10% of its battery power left. The router will then continue to monitor the UPS (while in hibernate mode) and then restart itself after when the utility power returns. If the UPS battery is drained and the router loses all power, the router will power back to full operation when the ‘utility’ power returns.

The UPS monitor feature on the MikroTik RouterOS supports

Specifications

Packages required: ups
License required: Level1
Submenu level: /system ups
Standards and Technologies: APC’s smart protocol
Hardware usage: Not significant

Related Documents

Description

Cabling

The APC UPS (BackUPS Pro or SmartUPS) requires a special serial cable. If no cable came with the UPS, a cable may be ordered from APC or one can be made “in-house”. Use the following diagram:

Note that you may also connect with USB if available.

UPS Monitor Setup

Submenu level: /system ups

Property Description

alarm-setting (delayed | immediate | low-battery | none; default: immediate) – UPS sound alarm setting:

load (read-only: percentage) – the UPS’s output load as a percentage of full rated load in Watts. The typical accuracy of this measurement is ±3% of the maximum of 105%manufacture-date (read-only: text) – the UPS’s date of manufacture in the format “mm/dd/yy” (month, day, year)min-runtime (time; default: 5m) – minimal run time remaining. After a ‘utility’ failure, the router will monitor the runtime-left value. When the value reaches the min-runtime value, the router will go to hibernate mode

model (read-only: text) – less than 32 ASCII character string consisting of the UPS model name (the words on the front of the UPS itself)nominal-battery-voltage (read-only: integer) – the UPS’s nominal battery voltage rating (this is not the UPS’s actual battery voltage)offline-time (time; default: 5m) – how long to work on batteries. The router waits that amount of time and then goes into hibernate mode until the UPS reports that the ‘utility’ power is back

port (name) – communication port of the routerserial (read-only: text) – a string of at least 8 characters directly representing the UPS’s serial number as set at the factory. Newer SmartUPS models have 12-character serial numbersversion (read-only: text) – UPS version, consists of three fields: SKU number, firmware revision, country code. The county code may be one of the following:

Notes

In order to enable UPS monitor, the serial port should be available.

Example

To enable the UPS monitor for port serial1:

[admin@MikroTik] system ups> add port=serial1 disabled=no
[admin@MikroTik] system ups> print
Flags: X - disabled, I - invalid
 0    name="ups" port=serial1 offline-time=5m min-runtime=5m
      alarm-setting=immediate model="SMART-UPS 1000" version="60.11.I"
      serial="QS0030311640" manufacture-date="07/18/00"
      nominal-battery-voltage=24V
[admin@MikroTik] system ups>

Runtime Calibration

Command name: /system ups rtc

Description

The rtc command causes the UPS to start a run time calibration until less than 25% of full battery capacity is reached. This command calibrates the returned run time value.

Notes

The test begins only if the battery capacity is 100%.

Example

[admin@MikroTik] system ups> rtc 0

UPS Monitoring

Command name: /system ups monitor

Property Description

battery-charge (percentage) – the UPS’s remaining battery capacity as a percent of the fully charged conditionbattery-voltage – the UPS’s present battery voltage. The typical accuracy of this measurement is ±5% of the maximum value (depending on the UPS’s nominal battery voltage)frequency (percentage) – when operating on-line, the UPS’s internal operating frequency is synchronized to the line within variations within 3 Hz of the nominal 50 or 60 Hz. The typical accuracy of this measurement is ±1% of the full scale value of 63 Hzline-voltage – the in-line utility power voltageload (percentage) – the UPS’s output load as a percentage of full rated load in Watts. The typical accuracy of this measurement is ±3% of the maximum of 105%low-battery – only shown when the UPS reports this statuson-battery (yes | no) – Whether UPS battery is supplying poweron-line (yes | no) – whether power is being provided by the external utility (power company)output-voltage – the UPS’s output voltageoverloaded-output – only shown when the UPS reports this statusreplace-battery – only shown when the UPS reports this statusruntime-calibration-running – only shown when the UPS reports this statusruntime-left (time) – the UPS’s estimated remaining run time in minutes. You can query the UPS when it is operating in the on-line, bypass, or on-battery modes of operation. The UPS’s remaining run time reply is based on available battery capacity and output loadsmart-boost-mode – only shown when the UPS reports this statussmart-ssdd-mode – only shown when the UPS reports this statustransfer-cause (text) – the reason for the most recent transfer to on-battery operation (only shown when the unit is on-battery)

Example

When running on utility power:

[admin@MikroTik] system ups> monitor 0
          on-line: yes
       on-battery: no
      RTC-running: no
     runtime-left: 20m
   battery-charge: 100%
  battery-voltage: 27V
     line-voltage: 226V
   output-voltage: 226V
             load: 45%
      temperature: 39C
        frequency: 50Hz
  replace-battery: no
      smart-boost: no
       smart-trim: no
         overload: no
      low-battery: no

[admin@MikroTik] system ups>

When running on battery:

[admin@MikroTik] system ups> monitor 0
          on-line: no
       on-battery: yes
   transfer-cause: "Line voltage notch or spike"
      RTC-running: no
     runtime-left: 19m
    offline-after: 4m46s
   battery-charge: 94%
  battery-voltage: 24V
     line-voltage: 0V
   output-voltage: 228V
             load: 42%
      temperature: 39C
        frequency: 50Hz
  replace-battery: no
      smart-boost: no
       smart-trim: no
         overload: no
      low-battery: no

      [admin@MikroTik] system ups>

©

Bahasa Indonesia

System watchdog feature is needed to reboot the system in case of software failures.

Specifications

Packages required: system
License required: Level1
Submenu level: /system watchdog
Standards and Technologies:
Hardware usage: Not significant

Hardware Watchdog Management

Submenu level: /system watchdog

Description

This menu allows to configure system to reboot on kernel panic, when an IP address does not respond, or in case the system has locked up. Software watchdog timer is used to provide the last option, so in very rare cases (caused by hardware malfunction) it can lock up by itself. There is a hardware watchdog device available in RouterBOARD hardware, which can reboot the system in any case.

Property Description

reboot-on-failure (yes | no; default: no) – whether to reboot on kernel panic watch-address (IP address; default: none) – if set, the system will reboot in case 6 sequental pings to the given IP address (sent once per 10 seconds) will fail

watchdog-timer (yes | no; default: no) – whether to reboot if system is unresponsive for a minute no-ping-delay (time; default: 5m) – specifies how long after reboot not to test and ping watch-address. The default setting means that if watch-address is set and is not reachable, the router will reboot about every 6 minutes. automatic-supout (yes | no; default: yes) – when software failure happens, a file named “autosupout.rif” is generated automatically. The previous “autosupout.rif” file is renamed to “autosupout.old.rif” auto-send-supout (yes | no; default: no) – after the support output file is automatically generated, it can be sent by email send-email-from (text; default: “”) – e-mail address to send the support output file from. If not set, the value set in /tool e-mail is used send-email-to (text; default: “”) – e-mail address to send the support output file to send-smtp-server (text; default: “”) – SMTP server address to send the support output file through. If not set, the value set in /tool e-mail is used

Example

To make system generate a support output file and sent it automatically to support@example.com throught the 192.0.2.1in case of a software crash:

[admin@MikroTik] system watchdog> set auto-send-supout=yes \
\... send-to-email=support@example.com send-smtp-server=192.0.2.1
[admin@MikroTik] system watchdog> print
  reboot-on-failure: yes
      watch-address: none
     watchdog-timer: yes
      no-ping-delay: 5m
   automatic-supout: yes
   auto-send-supout: yes
   send-smtp-server: 192.0.2.1
      send-email-to: support@example.com
[admin@MikroTik] system watchdog>

©

Bahasa Indonesia

The MikroTik RouterOS IP Telephony feature enables Voice over IP (VoIP) communications using routers equipped with the following voice port hardware:

Specifications

Packages required: telephony
License required: Level1
Submenu level: /ip telephony
Standards and Technologies: RTP
Hardware usage: Pentium MMX level processor recommended

Related Documents

Description

In PSTN lines there is a known delay of the signal caused by switching and signal compressing devices of the telephone network (so, it depends on the distance between the peers), which is generally rather low. The delay is also present in IP networks. The main difference between a PSTN and an IP network is that in IP networks that delay is more random. The actual packet delay may vary in order of magnutude in congested networks (if a network becomes congested, some packets may even be lost). Also packet reordering may take place. To prevent signal loss, caused by random jitter of IP networks and packet reordering, to corrupt audio signal, a jitter buffer is present in IP telephony devices. The jitter buffer is delaying the actual playback of a received packet forming The larger the jitter buffer, the larger the total delay, but fewer packets get lost due to timeout.

Notes

Each installed Quicknet card requires IO memory range in the following sequence: the first card occupies addresses 0×300-0x31f, the second card 0×320-0x33f, the third 0×340-0x35f, and so on. Make sure there is no conflict in these ranges with other devices, e.g., network interface cards, etc.

Use the telephony logging feature to debug your setup.

Additional Resources

IP Telephony Online

General Voice port settings

Submenu level: /ip telephony voice-port

Description

This submenu is used for managing all IP telephony voice ports (linejack, phonejack, isdn, voip, voicetronix, zaptel)

Property Description

name (name) – assigned name of the voice port type (read-only: phonejack | linejack | phonejack-lite | phonejack-pci | voip | isdn | voicetronix | zaptel) – type of the installed telephony voice port:

autodial (integer; default: “”) – number to be dialed automatically, if call is coming in from this voice port

Notes

Voicetronix Voice Ports

Submenu level: /ip telephony voice-port voicetronix

Property Description

name (name) – name given by the user or the default one autodial (integer; default: “”) – phone number which will be dialed immediately after the handset has been lifted. If this number is incomplete, then the remaining part has to be dialed on the dial-pad. If the number is incorrect, the line is hung up. If the number is correct, then the appropriate number is dialed (the direct-call mode is used – the line is picked up only after the remote party answers the call) playback-volume (integer: -48..48; default: 0) – playback volume in dB

record-volume (integer: -48..48; default: 0) – record volume in dB

region (name; default: us) – regional setting for the voice port. This setting is used for setting the parameters of PSTN line, as well as for detecting and generating the tones agc-on-playback (yes | no; default: no) – automatic gain control on playback (can not be used together with hardware voice codecs) agc-on-record (yes | no; default: no) – automatic gain control on record (can not be used together with hardware voice codecs) detect-cpt (yes | no; default: no) – automatically detect call progress tones balance-registers (integer: 0..255; default: 199) – registers which depend on telephone line impedance. Can be adjusted to get best echo cancellation. Should be changed only if echo cancellation on voicetronix card does not work good enough. Echo cancellation problems can imply DTMF and busy-tone detection failures. The value has to be in format bal1[,bal3[,bal2]], where bal1, bal2, bal3 – balance registers. bal1 has to be in interval 192..248 (0xC0..0xF8). The others should be in interval 0..255 (0×00..0xFF) balance-status (read-only: integer; default: unknown) – shows quality of hardware echo cancellation in dB loop-drop-detection (yes | no; default: yes) – automatically clear call when loop drop is detected

Command Description

test-balance – current balance-registers value is tested once. Result is placed in balance-status parameter. Balance can be tested only when line is off-hook. It won’t work if line is on-hook or there is an established connection

find-best-balance – series of test-balance is executed with different balance-registers values. During the tests balance-registers are updated to the best values found

clear-call – terminate a current call established with the specified voice port

show-stats – show voice port statistics

monitor – monitor status of the voice port

Notes

As some Voicetronix cards fail to detect loop drop correctly, with loop-drop-detection you can manage whether loop drop detection feature is enabled. The effect of not working loop-drop detection is call terminated at once when connection is established.

LineJack Voice Ports

Submenu level: /ip telephony voice-port linejack

Property Description

name (name) – name given by the user or the default one autodial (integer; default: “”) – phone number which will be dialed immediately after the handset has been lifted. If this number is incomplete, then the remaining part has to be dialed on the dial-pad. If the number is incorrect, the line is hung up (FXO “line” port) or busy tone is played (FXS “phone” port). If the number is correct, then the appropriate number is dialed. If it is an incomming call from the PSTN line, then the direct-call mode is used – the line is picked up only after the remote party answers the call playback-volume (integer: -48..48; default: 0) – playback volume in dB

record-volume (integer: -48..48; default: 0) – record volume in dB

ring-cadence (text) – a 16-symbol ring cadence for the phone, each symbol lasts 0.5 seconds, + means ringing, - means no ringing region (name; default: us) – regional setting for the voice port. This setting is used for setting the parameters of PSTN line, as well as for detecting and generating the tones aec (yes | no) – whether echo detection and cancellation is enabled aec-tail-length (short | medium | long; default: short) – size of the buffer of echo detection aec-nlp-threshold (off | low | medium | high; default: low) – level of cancellation of silent sounds aec-attenuation-scaling (integer: 0..10; default: 4) – factor of additional echo attenuation aec-attenuation-boost (integer: 0..90; default: 0) – level of additional echo attenuation software-aec (yes | no) – software echo canceller (experimental, for most of the cards) agc-on-playback (yes | no; default: no) – automatic gain control on playback (can not be used together with hardware voice codecs) agc-on-record (yes | no; default: no) – automatic gain control on record (can not be used together with hardware voice codecs) detect-cpt (yes | no; default: no) – automatically detect call progress tones

Command Description

blink – blink the LEDs of the specified voice port for five seconds after it is invoked. This command can be used to locate the respective card from several linejack cards

clear-call – terminate a current call established with the specified voice port

show-stats – show voice port statistics

monitor – monitor status of the voice port

Notes

When telephone line is connected to the ‘line’ port, green LED next to the port should be lit in some seconds. If telephone line disappear, the LED next to the ‘line’ port will change its state to red in an hour or when the line is activated (i.e. when somebody calls to/from it). When telephone line is plugged in the ‘phone’ port before the router is turned on, red LED next to the port will be lit. WARNING: do not plug telephone line into the ‘phone’ port when the router is running and green LED next to the port is lit – this might damage the card. The status of the ‘phone’ port is only detected on system startup.

PhoneJack Voice Ports

Submenu level: /ip telephony voice-port phonejack

Property Description

name (name) – name given by the user or the default one type (read-only: phonejack | phonejack-lite | phonejack-pci) – type of the card autodial (integer; default: “”) – phone number which will be dialed immediately after the handset has been lifted. If this number is incomplete, then the remaining part has to be dialed on the dial-pad. If the number is incorrect, busy tone is played. If the number is correct, then the appropriate number is dialed playback-volume (integer: -48..48; default: 0) – playback volume in dB

record-volume (integer: -48..48; default: 0) – record volume in dB

ring-cadence (text) – a 16-symbol ring cadence for the phone, each symbol lasts 0.5 seconds, + means ringing, - means no ringing region (name; default: us) – regional setting for the voice port. This setting is used for generating the dial tones aec (yes | no) – wheteher echo detection and cancellation is enabled aec-tail-length (short | medium | long; default: short) – size of the buffer of echo detection aec-nlp-threshold (off | low | medium | high; default: low) – level of cancellation of silent sounds aec-attenuation-scaling (integer: 0..10; default: 4) – factor of additional echo attenuation aec-attenuation-boost (integer: 0..90; default: 0) – level of additional echo attenuation software-aec (yes | no) – software echo canceller (experimental, for most of the cards) agc-on-playback (yes | no; default: no) – automatic gain control on playback (can not be used together with hardware voice codecs) agc-on-record (yes | no; default: no) – automatic gain control on record (can not be used together with hardware voice codecs) detect-cpt (yes | no; default: no) – automatically detect call progress tones

Command Description

clear-call – terminate a current call established with the specified voice port

show-stats – show voice port statistics

monitor – monitor status of the voice port

Zaptel Voice Ports

Submenu level: /ip telephony voice-port zaptel

Property Description

name (name) – name given by the user or the default one autodial (integer; default: “”) – phone number which will be dialed immediately after the handset has been lifted. If this number is incomplete, then the remaining part has to be dialed on the dial-pad. If the number is incorrect, the line is hung up. If the number is correct, then the appropriate number is dialed (the direct-call mode is used – the line is picked up only after the remote party answers the call) playback-volume (integer: -48..48; default: 0) – playback volume in dB

record-volume (integer: -48..48; default: 0) – record volume in dB

region (name; default: us) – regional setting for the voice port. This setting is used for setting the parameters of PSTN line, as well as for detecting and generating the tones aec (yes | no) – wheteher echo detection and cancellation is enabled aec-tail-length (short | medium | long; default: short) – size of the buffer of echo detection aec-nlp-threshold (off | low | medium | high; default: low) – level of cancellation of silent sounds aec-attenuation-scaling (integer: 0..10; default: 4) – factor of additional echo attenuation aec-attenuation-boost (integer: 0..90; default: 0) – level of additional echo attenuation software-aec (yes | no) – software echo canceller (experimental, for most of the cards) agc-on-playback (yes | no; default: no) – automatic gain control on playback (can not be used together with hardware voice codecs) agc-on-record (yes | no; default: no) – automatic gain control on record (can not be used together with hardware voice codecs) detect-cpt (yes | no; default: no) – automatically detect call progress tones

Command Description

clear-call – terminate a current call established with the specified voice port

show-stats – show voice port statistics

monitor – monitor status of the voice port

ISDN Voice Ports

Submenu level: /ip telephony voice-port isdn

Property Description

name (name) – name given by the user or the default one msn (integer) – telephone number of the ISDN voice port (ISDN MSN number) lmsn (text) – msn pattern to listen on. It determines which calls from the ISDN line this voice port should answer. If left empty, msn is used autodial (integer; default: “”) – phone number which will be dialed immediately on each incoming ISDN call. If this number contains ‘m’, then it will be replaced by originally called (ISDN) telephone number. If this number is incomplete, then the remaining part has to be dialed by the caller. If the number is incorrect, call is refused. If the number is correct, then the appropriate number is dialed. For that direct-call mode is used – the line is picked up only after the remote party answers the call playback-volume (integer: -48..48; default: 0) – playback volume in dB

record-volume (integer: -48..48; default: 0) – record volume in dB

region (name; default: us) – regional setting for the voice port. This setting is used for setting the parameters of PSTN line, as well as for detecting and generating the tones aec (yes | no) – wheteher echo detection and cancellation is enabled aec-tail-length (short | medium | long; default: short) – size of the buffer of echo detection software-aec (yes | no) – software echo canceller (experimental, for most of the cards) agc-on-playback (yes | no; default: no) – automatic gain control on playback (can not be used together with hardware voice codecs) agc-on-record (yes | no; default: no) – automatic gain control on record (can not be used together with hardware voice codecs)

Command Description

clear-call – terminate a current call established with the specified voice port

show-stats – show voice port statistics

monitor – monitor status of the voice port

Notes

In contrary to analog voice ports phonejack, linejack, voicetronix, zaptel), which are as many as the number of cards installed, the isdn ports can be added as many as desired.

Voice Port for Voice over IP (voip)

Submenu level: /ip telephony voice-port voip

Description

The voip voice ports are virtual ports, which designate a voip channel to another host over the IP network. You must have at least one voip voice port to be able to make calls to other H.323 devices over IP network.

Property Description

name (name) – name given by the user or the default one remote-address (IP address; default: 0.0.0.0) – IP address of the remote party (IP telephone or gateway) associated with this voice port. If the call has to be performed through this voice port, then the specified IP address is called. If there is an incoming call from the specified IP address, then the parameters of this voice port are used. If there is an incoming call from an IP address, which is not specified in any of the voip voice port records, then the default record is used. If there is no default record, then default values are used

autodial (integer) – phone number which will be added in front of the telephone number received over the IP network. In most cases it should be blank jitter-buffer (time: 0..1000ms; default: 100ms) – size of the jitter buffer

silence-detection (yes | no; default: no) – whether silence is detected and no audio data is sent over the IP network during the silence period prefered-codec (name; default: none) – the preferred codec to be used for this voip voice port. If possible, the specified codec will be used

fast-start (yes | no; default: yes) – allow or disallow the fast start. The fast start allows establishing the audio connection in a shorter time. However, not all H.323 endpoints support this feature. Therefore, it should be turned off, if there are problems to establish telephony connection using the fast start mode

Numbers

Description

Property Description

dst-pattern (integer) – pattern of the telephone number. Symbol ‘.’ designate any digit, symbol ‘_’ (only as the last one) designate any symbols (i.e. any number of characters can follow, ended with ‘#’ button) voice-port (name) – voice port to be used when calling the specified telephone number prefix (integer) – prefix, which will be used to substitute the known part of the dst-pattern, i.e., the part containing digits. The dst-pattern argument is used to determine which voice port to be used, whereas the prefix argument designates the number to dial over the voice port (be sent over to the remote party). If the remote party is an IP telephony gateway, then the number will be used for making the call

Notes

More than one entry can be added with exactly the same dst-pattern. If first one of them is already busy, next one with the same dst-pattern is used. Telephony number entries can be moved, to select desired order.

Example

Let us consider the following example for the number table:

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN                    VOICE-PORT PREFIX
  0     12345                          XX
  1     1111.                          YY
  2     22...                          ZZ         333
  3     ...                            QQ         55

[admin@MikroTik] ip telephony numbers>

We will analyze the Number Received (nr) – number dialed at the telephone, or received over the line, the Voice Port (vp) – voice port to be used for the call, and the Number to Call (nc) – number to be called over the Voice Port.

Let us add a few more records:

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN                    VOICE-PORT PREFIX
  0     12345                          XX
  1     1111.                          YY
  2     22...                          ZZ         333
  3     ...                            QQ         55
  4     222                            KK         44444
  5     3..                            LL         553

[admin@MikroTik] ip telephony numbers>

Let us add a few more records:

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN                    VOICE-PORT PREFIX
  0     12345                          XX
  1     1111.                          YY
  2     22...                          ZZ         333
  3     ...                            QQ         55
  4     222                            KK         44444
  5     3..                            LL         553
  6     33...                          MM         33
  7     11.                            NN         7711

[admin@MikroTik] ip telephony numbers>

It is impossible to add the following records:

  #     DST-PATTERN                    VOICE-PORT PREFIX
                                                              reason:
        11                             DD               conflict with record # 1
                                                        and # 7
        11..                           DD               conflict with record # 7
        111                            DD               conflict with record # 1
        22.                            DD               conflict with record # 2
        .....                          DD               conflict with record # 3

Regional Settings

Submenu level: /ip telephony region

Description

Regional settings are used to adjust the voice port properties to the PSTN system or the PBX. For example, to detect hang-up from line, there has to be correct regional setting (correct busy-tone-frequency and busy-tone-cadence). Without that, detect-cpt parameter the voice port has to be enabled.

Property Description

name (name) – name of the regional setting busy-tone-cadence (integer: 0..30000; default: 500,500) – busy tone cadence in ms

busy-tone-frequency (integer: 20..2000integer: -24..6; default: 440×0) – frequency and volume gain of busy tone, Hz x dB data-access-arrangement (australia | france | germany | japan | uk | us; default: us) – ring voltage, impedance setting for line-jack card dial-tone-frequency (integer: 20..2000integer: -24..6; default: 440×0) – frequency and volume gain of dial tone, Hz x dB dtmf-tone-cadence (integer: 0..30000; default: 180,60) – Dual Tone Multi Frequency tone cadence in ms

dtmf-tone-volume (integer: -24..6; default: -3,-3) – Dual Tone Multi Frequency tone volume in dB ring-tone-cadence (integer: 0..30000; default: 1000,2000) – Ring tone cadence in ms

ring-tone-frequency (integer: 20..2000integer: -24..6; default: 440×0) – frequency and volume gain of busy tone, Hz x dB

Notes

To generate a tone, frequency and cadence arguments are used. The dialtone always is continuous signal, therefore it does not have the cadence argument. In order to detect dialtone, it should be at least 100ms long.

There are 10 pre-defined regions, which can not be deleted (but may be changed)

Audio CODECs

Submenu level: /ip telephony codec

Description

CODECs are listed according to their priority of use. The highest priority is at the top. CODECs can be enabled, disabled and moved within the list. When connecting with other H.323 systems, the protocol will negotiate the CODEC which both of them support according to the priority order.

The hardware codecs (/hw) are built-in CODECs supported by some cards.

The choice of the CODEC type is based on the throughput and speed of the network. Better audio quality can be achieved by using CODEC requiring higher network throughput. The highest audio quality can be achieved by using the G.711-uLaw CODEC requiring 64kb/s throughput for each direction of the call. It is used mostly within a LAN. The G.723.1 CODEC is the most popular one to be used for audio connections over the Internet. It requires only 6.3kb/s throughput for each direction of the call.

Example

[admin@MikroTik] ip telephony codec> print
Flags: X - disabled
  #   NAME
  0   G.723.1-6.3k/sw
  1   G.728-16k/hw
  2   G.711-ALaw-64k/hw
  3   G.711-uLaw-64k/hw
  4   G.711-uLaw-64k/sw
  5   G.711-ALaw-64k/sw
  6   G.729A-8k/sw
  7   GSM-06.10-13.2k/sw
  8   LPC-10-2.5k/sw
  9   G.723.1-6.3k/hw
 10   G.729-8k/sw
[admin@MikroTik] ip telephony codec>

AAA

Submenu level: /ip telephony aaa

Description

AAA (Authentication Authorization Accounting) can be used to configure the RADIUS accounting feature.

Property Description

use-radius-accounting (yes | no; default: no) – whether to use radius accounting or not interim-update (integer; default: 0) – defines time interval between communications with the router. If this time will exceed, RADIUS server will assume that this connection is down. This value is suggested not to be less than 3 minutes

Notes

All the parameters, which names begin with h323, are CISCO vendor specific Radius attributes

Gatekeeper

Submenu level: /ip telephony gatekeeper

Description

For each H.323 endpoint gatekeeper stores its telephone numbers. So, gatekeeper knows all telephone numbers for all registered endpoints. And it knows which telephone number is handled by which endpoint. Mapping between endpoints and their telephone numbers is the main functionality of gatekeepers.

If endpoint is registered to endpoint, it does not have to know every single endpoint and every single telephone number, which can be called. Instead, every time some number is dialed, endpoint asks gatekeeper for destination endpoint to call by providing called telephone number to it.

MikroTik IP telephony package includes a very simple gatekeeper. This gatekeeper can be activated by setting gatekeeper parameter to local. In this case the local endpoint automatically is registered to the local gatekeeper. And any other endpoint can register to this gatekeeper too.

Registered endpoints are added to the /ip telephony voice-port voip table. Those entries are marked as dynamic and can not be removed or changed. If there already was an voip entry with the same IP address, it is marked as registred. Remote-address can not be changed for these entries too, but registered voip voice ports can be removed – they will stay as dynamic ones. If there already is a dynamic voip voice port and a static one with the same IP address is added, then instead of dynamic entry, registered will appear.

Dynamic entries disappear when corresponding endpoint unregisters itself from the gatekeeper. Registered entries are static and will stay even after that endpoint will be unregistered from this gatekeeper.

Registered telephone numbers are added to /ip telephony numbers table. Here is exactly the same idea behind dynamic and registered telephone numbers as it is with voip voice ports.

When an endpoint registers to the gatekeeper, it sends its own telephone numbers (aliases and prefixes) within this registration request. /ip telephony numbers entry is registered to the endpoint only if voice-port for that entry is local (not voip). If dst-pattern contains ‘.’ or ‘_’, it is sent as prefix, otherwise – as alias. The known part of the dst-pattern is sent as prefix. If there is no known part (dst-pattern is “_” or “…”, for example), then this entry is not sent at all.

Property Description

gatekeeper (none | local | remote; default: none) – Gatekeeper type to use

remote-address (IP address; default: 0.0.0.0) – IP address of remote gatekeeper to use. If set to 0.0.0.0, broadcast gatekeeper discovery is used remote-id (name) – name of remote gatekeeper to use. If left empty, first available gatekeeper will be used. Name of locally started gatekeeper is the same as system identity registered (read-only: yes | no) – shows whether local H.323 endpoint is registered to any gatekeeper registered-with (read-only: name) – name of gatekeeper to which local H.323 endpoint is registered

Example

In most simple case with one phonejack card and some remote gatekeeper, configuration can be as follows:

[admin@MikroTik] ip telephony voice-port> print
Flags: X - disabled
  #   NAME                          TYPE            AUTODIAL
  0   phonejack1                phonejack
  1   voip1                         voip

[admin@MikroTik] ip telephony voice-port voip> print
Flags: X - disabled, D - dynamic, R - registered
  #    NAME      AUTODIAL REMOTE-ADDRESS  JITTER-BUFFER PREFERED-CODEC  SIL FAS
  0    voip1              0.0.0.0         0s            none            no  yes

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN             VOICE-PORT              PREFIX
  0     11                      phonejack1
  1     _                       voip1

[admin@MikroTik] ip telephony gatekeeper> print
         gatekeeper: remote
          remote-id: ""
     remote-address: 10.0.0.98
         registered: yes
    registered-with: "MikroTik@10.0.0.98"

In this case this endpoint will register to gatkeeper with the IP address of 10.0.0.98 and telephone number 11. Every call to telephone number 11 will be transfered from gatekeeper to this endpoint. And this endpoint will route this call to phonejack1 voice port. On any other telephone number gatekeeper will be asked for real destination. From this endpoint it will be possible to call all the endpoints, which are registered to the same gatekeeper. If that gatekeeper has static entries about endpoints, which are not registered to gatekeeper, it still will be possible to call those endpoints by those statically defined telephone numbers at gatekeeper.

Example

For example, if numbers table is like this:

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN             VOICE-PORT              PREFIX
  0     1.                      phonejack1
  1     128                     voip1                   128
  2     78                      voip2                   78
  3     77                      phonejack1
  4     76                      phonejack1              55
  5     _                       voip1

then entries 0, 3 and 4 will be sent to the gatekeeper, others are voip voice ports and are ignored. Entry 0 will be sent as prefix 1, entry 3 – as alias 77, and entry 4 – as alias 76.

If IP address of local endpoint is 10.0.0.100, then gatekeeper voip and numbers tables will look as follows:

      [admin@MikroTik] ip telephony voice-port voip> print
Flags: X - disabled, D - dynamic, R - registered
  #    NAME      AUTODIAL REMOTE-ADDRESS  JITTER-BUFFER PREFERED-CODEC  SIL FAS
  0    tst-2.5            10.0.0.101      0s            none            no  yes
  1  D local              127.0.0.1       100ms         none            no  yes
  2  D 10.0.0...          10.0.0.100      100ms         none            no  yes

[admin@MikroTik] ip telephony numbers> print
Flags: I - invalid, X - disabled, D - dynamic, R - registered
  #     DST-PATTERN             VOICE-PORT              PREFIX
  0     78                      linejack1
  1     3...                    vctx1
  2     33_                     voip1
  3     5..                     voip1
  4  XD 78                      local                   78
  5  XD 3_                      local                   3
  6   D 76                      10.0.0.100              76
  7   D 77                      10.0.0.100              77
  8   D 1_                      10.0.0.100              1

Here we can see how aliases and prefixes are added to numbers table. Entries 0..3 are static. Entries 4 and 5 are added by registering the local endpoint to the local gatekeeper. Entries 6..8 are added by registering endpoint (with IP address 10.0.0.100) to the local gatekeeper.

For prefixes, ‘_’ is added at the end of dst-pattern to allow any additional digits to be added at the end.

Local endpoint is registered to the local gatekeeper too. So, local aliases and prefixes are added as dynamic numbers too. Only, as they are local and corresponding number entries already exist in the number table, then these dynamically added entries are disabled by default.

If any registered telephone number will conflict with some existing telephone numbers entry, it will be added as disabled and dynamic.

If in gatekeeper’s numbers table there already exists exactly the same dst-pattern as some other endpoint is trying to register, this gatekeeper registration for that endpoint will fail.

Troubleshooting

Description

A simple example

Description

The following describes examples of some useful IP telephony applications using MikroTik RouterOS.

Let us consider the following example of IP telephony gateway, one MikroTik IP telephone, and one Welltech LAN Phone 101 setup:

Setting up the MikroTik IP Telephone

If you pick up the handset, a dialtone should be heard.

Setting up the IP Telephony Gateway

The IP telephony gateway [voip_gw] requires the following configuration:

Setting up the Welltech IP Telephone

Please follow the documentation from www.welltech.com.tw on how to set up the Welltech LAN Phone 101. Here we give just brief recommendations:

Use the telephony logging feature on the gateway to debug your setup.

Setting up MikroTik Router and CISCO Router

Let’s try a different example.

Here are some hints on how to get working configuration for telephony calls between CISCO and MikroTik router.

For reference, following is an exported CISCO configuration, that works:

!
version 12.1
no service single-slot-reload-enable
service timestamps debug uptime
service timestamps log uptime
no service password-encryption
!
hostname Router
!
logging rate-limit console 10 except errors
enable secret 5 $1$bTMC$nDGl9/n/pc3OMbtWxADMg1
enable password 123
!
memory-size iomem 25
ip subnet-zero
no ip finger
!
call rsvp-sync
voice rtp send-recv
!
voice class codec 1
 codec preference 1 g711ulaw
 codec preference 2 g723r63
!
interface FastEthernet0
 ip address 10.0.0.101 255.255.255.0
 no ip mroute-cache
 speed auto
 half-duplex
!
ip classless
ip route 0.0.0.0 0.0.0.0 10.0.0.1
no ip http server
!
dialer-list 1 protocol ip permit
dialer-list 1 protocol ipx permit
!
voice-port 0/0
!
voice-port 0/1
!
voice-port 2/0
!
voice-port 2/1
!
dial-peer voice 1 pots
 destination-pattern 101
 port 0/0
!
dial-peer voice 97 voip
 destination-pattern 097
 session target ipv4:10.0.0.97
 codec g711ulaw
!
dial-peer voice 98 voip
 destination-pattern 098
 voice-class codec 1
 session target ipv4:10.0.0.98
!
!
line con 0
 transport input none
line aux 0
line vty 0 4
 password 123
 login
!
end

Setting up PBX to PBX Connection over an IP Network

To interconnect two telephone switchboards (PBX) over an IP network, two IP telephony gateways should be configured. The setup is shown in the following diagram:

We want to be able to use make calls from local telephones of one PBX to local telephones or external lines of the other PBX.

The system works as follows:

To dial from the main office PBX#1 any extension of the remote office PBX#2, the extension with the connected gateway at PBX#1 should be dialed first. Then, after the dial tone of the gateway#1 is received, the remote extension number should be dialed.

To dial from the main office PBX#2 any extension of the remote office PBX#1, the actions are the same as in first situation.

©

Bahasa Indonesia

Traffic monitor executes scripts on a specific datarate throough an interface.

Specifications

Packages required: advanced-tools
License required: Level1
Submenu level: /tool traffic-monitor
Standards and Technologies: none
Hardware usage: Not significant

Related Documents

Traffic Monitor

Submenu level: /tool traffic-monitor

Description

The traffic monitor tool is used to execute console scripts when interface traffic crosses a given threshold. 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.

Property Description

interface (name) – interface to monitorname (name) – name of the traffic monitor itemon-event (name) – script source. Must be present under /system script threshold (integer; default: 0) – traffic thresholdtraffic (transmitted | received; default: transmitted) – type of traffic to monitor

trigger (above | always | below; default: above) – condition on which to execute the script

Example

In this example the traffic monitor enables the interface ether2, if the received treffic exceeds 15kbps on ether1, and disables the interface ether2, if the received traffic falls below 12kbps on ether1.

[admin@MikroTik] system script> add name=eth-up source={/interface enable ether2}
[admin@MikroTik] system script> add name=eth-down source={/interface disable
{... ether2}
[admin@MikroTik] system script> /tool traffic-monitor
[admin@MikroTik] tool traffic-monitor> add name=turn_on interface=ether1 \
\... on-event=eth-up threshold=15000 trigger=above traffic=received
[admin@MikroTik] tool traffic-monitor> add name=turn_off interface=ether1 \
\... on-event=eth-down threshold=12000 trigger=below traffic=received
[admin@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
[admin@MikroTik] tool traffic-monitor>

©

Bahasa Indonesia

System Scheduler executes scripts at designated time.

Specifications

Packages required: system
License required: Level1
Submenu level: /system scheduler
Standards and Technologies: None
Hardware usage: Not significant

Related Documents

Scheduler Configuration

Description

The scheduler can trigger script execution at a particular time moment, after a specified time interval, or both.

Property Description

interval (time; default: 0s) – interval between two script executions, if time interval is set to zero, the script is only executed at its start time, otherwise it is executed repeatedly at the time interval is specified name (name) – name of the task on-event (name) – name of the script to execute. It must be presented at /system script run-count (read-only: integer) – to monitor script usage, this counter is incremented each time the script is executed start-date (date) – date of the first script execution start-time (time) – time of the first script execution

Notes

Rebooting the router will reset run-count counter.

If more than one script has to be executed simultaneously, they are executed in the order they appear in the scheduler configuration. This can be important if one scheduled script is used to disable another one. 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.

if scheduler item has start-time set to startup, it behaves as if start-time and start-date were set to time 3 seconds after console starts up. It means that all scripts having start-time=startup and interval=0 will be executed once each time router boots.

Example

We will add a task that executes the script log-test every hour:

[admin@MikroTik] system script> add name=log-test source=:log message=test
[admin@MikroTik] system script> print
    0 name="log-test" source=":log messgae=test" owner=admin run-count=0
[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add name=run-1h interval=1h
on-event=log-test
[admin@MikroTik] system scheduler> print

Flags: X - disabled
 #   NAME      ON-EVENT  START-DATE  START-TIME INTERVAL     RUN-COUNT
 0   run-1h    log-test  mar/30/2004 06:11:35   1h           0
[admin@MikroTik] system scheduler>

In another example there will be two scripts added that will change the bandwidth setting of a queue rule “Cust0″. Every day 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:

[admin@MikroTik] queue simple> add name=Cust0 interface=ether1 \
\... dst-address=192.168.0.0/24 limit-at=64000
[admin@MikroTik] queue simple> print
Flags: X - disabled, I - invalid
  0   name="Cust0" target-address=0.0.0.0/0 dst-address=192.168.0.0/24
      interface=ether1 limit-at=64000 queue=default priority=8 bounded=yes

[admin@MikroTik] queue simple> /system script
[admin@MikroTik] system script> add name=start_limit source={/queue simple set \
\... Cust0 limit-at=64000}
[admin@MikroTik] system script> add name=stop_limit source={/queue simple set \
\... Cust0 limit-at=128000}
[admin@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

[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add interval=24h name="set-64k" \
\... start-time=9:00:00 on-event=start_limit
[admin@MikroTik] system scheduler> add interval=24h name="set-128k" \
\... start-time=17:00:00 on-event=stop_limit
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      ON-EVENT START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   set-64k   start... oct/30/2008 09:00:00   1d                   0
  1   set-128k  stop_... oct/30/2008 17:00:00   1d                   0
[admin@MikroTik] system scheduler>

The following example schedules a script that sends each week a backup of router configuration by e-mail.

[admin@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}
[admin@MikroTik] system script> print
  0 name="e-backup" source="/system backup save name=ema... owner=admin
    run-count=0

[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add interval=7d name="email-backup" \
\... on-event=e-backup
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      ON-EVENT START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   email-... e-backup oct/30/2008 15:19:28   7d                   1
[admin@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:

[admin@MikroTik] tool e-mail> set server=159.148.147.198 from=SysAdmin@host.com
[admin@MikroTik] tool e-mail> print
    server: 159.148.147.198
      from: SysAdmin@host.com
[admin@MikroTik] tool e-mail>

Example below will put ‘x’ in logs each hour from midnight till noon:

[admin@MikroTik] system script> add name=enable-x source={/system scheduler
{... enable x}
[admin@MikroTik] system script> add name=disable-x source={/system scheduler
{... disable x}
[admin@MikroTik] system script> add name=log-x source={:log message=x}
[admin@MikroTik] system script> .. scheduler
[admin@MikroTik] system scheduler> add name=x-up start-time=00:00:00 \
\... interval=24h on-event=enable-x
[admin@MikroTik] system scheduler> add name=x-down start-time=12:00:00
\... interval=24h on-event=disable-x
[admin@MikroTik] system scheduler> add name=x start-time=00:00:00 interval=1h \
\... on-event=log-x
[admin@MikroTik] system scheduler> print
Flags: X - disabled
  #   NAME      ON-EVENT START-DATE  START-TIME INTERVAL             RUN-COUNT
  0   x-up      enable-x oct/30/2008 00:00:00   1d                   0
  1   x-down    disab... oct/30/2008 12:00:00   1d                   0
  2   x         log-x    oct/30/2008 00:00:00   1h                   0
[admin@MikroTik] system scheduler>

©

Bahasa Indonesia

This manual provides 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 occurence. A script consists of configuration commands and expressions (ICE – internal console expression). The configuration commands are standard RouterOS commands, e.g. /ip firewall filter add chain=forward protocol=gre action=drop that are described in the relevant manuals, while expressions are prefixed with : and are accessible from all submenus.

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.

Specifications

Packages required: system
License required: Level1
Submenu level: /system script
Standards and Technologies: None
Hardware usage: Not significant

Related Documents

Console Command Syntax

Description

Console commands are made of the following parts, listed in the order you type them in console:

Notes

Variable substitution, command substitution and expressions are allowed only for path_args and unnamed parameter values. prefix, path, action and name[=value] pairs can be given only directly, as a word. Therefore, :put (1 + 2) is valid and "pu" . "t") 3 is not.

Example

The parts of internal console commands are futher explained in the following examples:

/ping 10.0.0.1 count=5

.. ip firewall rule input

:for i from=1 to=10 do={:put $i}

/interface monitor-traffic ether1,ether2,ipip1

Expression Grouping

Description

This feature provides an easy way to execute commands from within one command level, by enclosing them in braces ‘{ }’.

Notes

Subsequent script commands are executed from the same menu level as the entire script. Consider the following example:

[admin@MikroTik] ip route> /user {
{... /ip route
{... print}
Flags: X - disabled
 #   NAME                                                              GROUP ADDRESS
 0   ;;; system default user
     admin                                                             full  0.0.0.0/0
 1   uuu                                                               full  0.0.0.0/0
[admin@MikroTik] ip route>

Although the current command level is changed to /ip route, it has no effect on next commands entered from prompt, therefore print command is still considered to be /user print.

Example

The example below demonstrates how to add two users to the user menu.

[admin@MikroTik] ip route> /user {
{... add name=x password=y group=write
{... add name=y password=z group=read
{... print}
Flags: X - disabled
 #   NAME                                                      GROUP ADDRESS
 0   ;;; system default user
     admin                                                     full  0.0.0.0/0
 1   x                                                         write 0.0.0.0/0
 2   y                                                         read  0.0.0.0/0
[admin@MikroTik] ip route>

Variables

Description

RouterOS scripting language suports two types of variables, which are global (system wide) and local (accessible only within the current script), respectively. A variable can be referenced by ‘$’ (dollar) sign followed by the name of the variable with the exception of set and unset commands that take variable name without preceding dollar sign. Variable names should be composed of contain letters, digits and ‘-’ character. A variable must be declared prior to using it in scripts. There are four types of declaration available:

You can assign a new value to variable using set action. It takes two unnamed parameters: the name of the variable and the new value of the variable. If a variable is no longer needed, it’s name can be freed by :unset command. If you free local variable, it’s value is lost. If you free global variable, it’s value is still kept in router, it just becomes inaccessible from current script.

Notes

Loop variables “shadows” already introduced variables with the same name.

Example

[admin@MikroTik] ip route> /
[admin@MikroTik] > :global g1 "this is global variable"
[admin@MikroTik] > :put $g1
this is global variable
[admin@MikroTik] >

Command Substitution and Return Values

Description

Some console commands are most useful if their output can be feed to other commands as an argument value. In RouterOS console this is done by using the return values from commands. Return values are not displayed on the screen. To get the return value from a command, it should be enclosed in square brackets ‘[ ]‘. Upon execution the return value of the the command will become the value of these brackets. This is called command substitution.

The commands that produce return values are, but not limited to: find, which returns a reference to a particular item, ping, which returns the number of sucessful pings, time, which returns the measured time value, incr and decr, which return the new value of a variable, and add, which returns the internal number of newly created item.

Example

Consider the usage of find command:

[admin@MikroTik] > /interface
[admin@MikroTik] interface> find type=ether
[admin@MikroTik] interface>
[admin@MikroTik] interface> :put [find type=ether]
*1,*2
[admin@MikroTik] interface>

This way you can see internal console numbers of items. Naturally, you can use them as arguments in other commands:

[admin@MikroTik] interface> enable [find type=ether]
[admin@MikroTik] interface>

Operators

Description

RouterOS console can do simple calculations with numbers, time values, IP addresses, strings and lists. To get result from an expression with operators, enclose it in parentheses ‘(‘ and ‘)’. The expression result serves as a return value for the parentheses.

Command Description

- – unary minus. Inverts given number value.- – binary minus. Substracts two numbers, two time values, two IP addresses or an IP address and a number! – logical NOT. Unary operator, which inverts given boolean value/ – division. Binary operator. Divides one number by another (gives number) or a time value by a number (gives time value).. – concatenation. Binary operator, concatenates two string or append one list to another or appends an element to a list.^ – bitwise XOR. The argumens and the result are both IP addresses~ – bit inversion. Unary operator, which inverts bits in IP address* – multiplication. Binary operator, which can multiply two numbers or a time value by a number.& – bitwise AND The argumens and the result are both IP addresses&& – logical AND. Binary operator. The argumens and the result are both logical values+ – binary plus. Adds two numbers, two time values or a number and an IP address.< – less. Binary operator which compares two numbers, two time values or two IP addresses. Returns boolean value<< – left shift. Binary operator, which shifts IP address by a given amount of bits. The first argument is an IP address, the second is an integer and the result is an IP address.<= – less or equal. Binary operator which compares two numbers, two time values or two IP addresses. Returns boolean value> – greater. Binary operator which compares two numbers, two time values or two IP addresses. Returns boolean value>= – greater or equal. Binary operator which compares two numbers, two time values or two IP addresses. Returns boolean value>> – right shift. Binary operator, which shifts IP address by a given amount of bits. The first argument is an IP address, the second is an integer and the result is an IP address.| – bitwise OR. The argumens and the result are both IP addresses|| – logical OR. Binary operator. The argumens and the result are both logical values

Notes

When comparing two arrays note, that two arrays are equal only if their respective elements are equal.

Example

Operator priority and evaluation order

[admin@MikroTik] ip firewall rule forward> :put (10+1-6*2=11-12=2+(-3)=-1)
false
[admin@MikroTik] ip firewall rule forward> :put (10+1-6*2=11-12=(2+(-3)=-1))
true
[admin@MikroTik] ip firewall rule forward

logical NOT

[admin@MikroTik] interface> :put (!true)
false
[admin@MikroTik] interface> :put (!(2>3))
true
[admin@MikroTik] interface>

unary minus

[admin@MikroTik] interface> :put (-1<0)
true
[admin@MikroTik] >
1

bit inversion

[admin@MikroTik] interface> :put (~255.255.0.0)
0.0.255.255
[admin@MikroTik] interface>

sum

[admin@MikroTik] interface> :put (3ms + 5s)
00:00:05.003
[admin@MikroTik] interface> :put (10.0.0.15 + 0.0.10.0)
cannot add ip address to ip address
[admin@MikroTik] interface> :put (10.0.0.15 + 10)
10.0.0.25
[admin@MikroTik] interface>

subtraction

[admin@MikroTik] interface> :put (15 - 10)
5
[admin@MikroTik] interface> :put (10.0.0.15 - 10.0.0.3)
12
[admin@MikroTik] interface> :put (10.0.0.15 - 12)
10.0.0.3
[admin@MikroTik] interface> :put (15h - 2s)
14:59:58
[admin@MikroTik] interface>

multiplication

[admin@MikroTik] interface> :put (12s * 4)
00:00:48
[admin@MikroTik] interface> :put (-5 * -2)
10
[admin@MikroTik] interface>

division

[admin@MikroTik] interface> :put (10s / 3)
00:00:03.333
[admin@MikroTik] interface> :put (5 / 2)
2
[admin@MikroTik] interface>
[admin@MikroTik] > :put (0:0.10 / 3)
00:00:02
[admin@MikroTik] >

comparison

[admin@MikroTik] interface> :put (10.0.2.3<=2.0.3.10)
false
[admin@MikroTik] interface> :put (100000s>27h)
true
[admin@MikroTik] interface> :put (60s,1d!=1m,3600s)
true
[admin@MikroTik] interface> :put (bridge=routing)
false
[admin@MikroTik] interface> :put (yes=false)
false
[admin@MikroTik] interface> :put (true=aye)
false
[admin@MikroTik] interface>

logical AND, logical OR

[admin@MikroTik] interface> :put ((yes && yes) || (yes && no))
true
[admin@MikroTik] interface> :put ((no || no) && (no || yes))
false
[admin@MikroTik] interface>

bitwise AND, bitwise OR, bitwise XOR

[admin@MikroTik] interface> :put (10.16.0.134 & ~255.255.255.0)
0.0.0.134
[admin@MikroTik] interface>

shift operators

[admin@MikroTik] interface> :put (~((0.0.0.1 << 7) - 1))
255.255.255.128
[admin@MikroTik] interface>

Concatenation

[admin@MikroTik] interface> :put (1 . 3)
13
[admin@MikroTik] interface> :put (1,2 . 3)
1,2,3
[admin@MikroTik] interface> :put (1 . 3,4)
13,4
[admin@MikroTik] interface> :put (1,2 . 3,4)
1,2,3,4
[admin@MikroTik] interface> :put ((1 . 3) + 1)
14
[admin@MikroTik] interface>

Data types

Description

The RouterOS console differentiates between several data types, which are string, boolean, number, time interval, IP address, internal number and list. The console tries to convert any value to the most specific type first, backing if it fails. The order in which the console attempts to convert an entered value is presented below:

Internal scripting language supplies special functions to explicitly control type conversion. The toarray, tobool, toid, toip, tonum, tostr and totime functions convert a value accordingly to list, boolean, internal number, IP address, number, string or time.

The number type is internally represented as 64 bit signed integer, so the value a number type variable can take is in range from -9223372036854775808 to 9223372036854775807. It is possible to input number value in hexadecimal form, by prefixing it with 0x, e.g.:

[admin@MikroTik] > :global MyVar 0x10
[admin@MikroTik] > :put $MyVar
16
[admin@MikroTik] >

Lists are treated as comma separated sequence of values. Putting whitespaces around commas is not recommended, because it might confuse console about words’ boundaries.

Boolean values can be either true or false. Console also accepts yes for true, and no for false.

Internal numbers are preceided * sign.

Time intervals can be entered either using HH:MM:SS.MS notation, e.g.:

[admin@MikroTik] > :put 01:12:1.01
01:12:01.010
[admin@MikroTik] >

or as sequence of numbers, optionally followed by letters specifying the units of time measure (d dor days, h for hours, m for minutes, s for seconds and ms for milliseconds), e.g.:

[admin@MikroTik] > :put 2d11h12
2d11:00:12
[admin@MikroTik] >

As can bee seen, time values with omitted unit specificators are treated as expressed in seconds.

The console also accepts time values with decimal point:

[admin@MikroTik] > :put 0.1day1.2s
02:24:01.200
[admin@MikroTik] >

Command Reference

Description

RouterOS has a number of built-in console commands and expressions (ICE) that do not depend on the current menu level. These commands do not change configuration directly, but they are useful for automating various maintenance tasks. The full ICE list can be accessed by typing ‘?’ after the ‘:’ prefix (therefore it can be safely assumed that all ICE have ‘:’ prefix), for example:

[admin@MikroTik] > :
beep         execute  global  list     pick     time     toip    typeof
delay        find     if      local    put      toarray  tonum   while
do           for      led     log      resolve  tobool   tostr
environment  foreach  len     nothing  set      toid     totime
[admin@MikroTik] >

Command Description

beep – forces the built-in PC beeper to produce a signal for length seconds at frequency Hz.

[admin@MikroTik] > :beep length=2s frequency=10000

[admin@MikroTik] >

delay – does nothing for a given amount of time.

do – executes commands repeatedly until given conditions are met. If no parameters are given, do just executes its payload once, which does not make much use. If a logical condition is specified for the while parameter, it will be evaluated after executing commands, and in case it is true, do statement is executed again and again until false. The if parameter, if present, is evaluated only once before doing anything else, and if it is false then no action is taken

[admin@MikroTik] > {:global i 10; :do {:put $i; :set i ($i - 1);} \
\... while (($i < 11) && ($i > 0)); :unset i;}
10
9
8
7
6
5
4
3
2
1
[admin@MikroTik] >

environment print – prints information about variables that are currently initialised. All global variables in the system are listed under the heading Global Variables. All variables that are introduced in the current script (variables introduced by :local or created by :for or :foreach statements) are listed under the heading Local Variables.

[admin@MikroTik] > :local A "This is a local variable"
[admin@MikroTik] > :global B "This is a global one"
[admin@MikroTik] > :environment print
Global Variables
B=This is a global one
Local Variables
A=This is a local variable
[admin@MikroTik] >

find – searches for substring inside a string or for an element with particular value inside an array, depending on argument types and returns position at which the value is found. The elements in list and characters in string are numbered from 0 upwards

[admin@MikroTik] interface pppoe-server> :put [:find "13sdf1sdfss1sfsdf324333"  ]
0
[admin@MikroTik] interface pppoe-server> :put [:find "13sdf1sdfss1sfsdf324333" 3  ]
1
[admin@MikroTik] interface pppoe-server> :put [:find "13sdf1sdfss1sfsdf324333" 3  3]
17
[admin@MikroTik] interface pppoe-server> :put [:find "1,1,1,2,3,3,4,5,6,7,8,9,0,1,2,3" 3 ]
4
[admin@MikroTik] interface pppoe-server> :put [:find "1,1,1,2,3,3,4,5,6,7,8,9,0,1,2,3" 3 3]
4
[admin@MikroTik] interface pppoe-server> :put [:find "1,1,1,2,3,3,4,5,6,7,8,9,0,1,2,3" 3 4]
5
[admin@MikroTik] interface pppoe-server> :put [:find "1,1,1,2,3,3,4,5,6,7,8,9,0,1,2,3" 3 5]
15
[admin@MikroTik]

for – executes supplied commands over a given number of iterations, which is explicity set through from and to

parameters

[admin@MikroTik] > :for i from=1 to=100 step=37  do={:put ($i . " - " . 1000/$i)}
1 - 1000
38 - 26
75 - 13
[admin@MikroTik] >

foreach – executes supplied commands for each element in list

:foreach i in=[/interface find type=ether ] \
\... do={:put ("+--" . [/interface get $i name]); \
\... :foreach j in=[/ip address find interface=$i]
\... do={:put ("|  `--" . [/ip address get $j address])}}
+--ether1
|  `--1.1.1.3/24
|  `--192.168.50.1/24
|  `--10.0.0.2/24
+--ether2
|  `--10.10.0.2/24
[admin@MikroTik] >

global – declares global variable

[admin@MikroTik] > :global MyString "This is a string"
[admin@MikroTik] > :global IPAddr 10.0.0.1
[admin@MikroTik] > :global time   0:10
[admin@MikroTik] > :environment print
Global Variables
IPAddr=10.0.0.1
time=00:10:00
MyString=This is a string
Local Variables
[admin@MikroTik] >

if – conditional statement. If a given logical condition evaluates to true then the do block of commands is executed. Otherwice an optional else block is executed.

[admin@MikroTik] > :if ([:len [/ip firewall filter find]] > 0) do={:put true} else={:put false}
true
[admin@MikroTik] >

[admin@MikroTik] > :if ([/ping 10.0.0.254 count=1] = 0) do {:put "gateway unreachable"}
10.0.0.254 ping timeout
1 packets transmitted, 0 packets received, 100% packet loss
gateway unreachable
[admin@MikroTik] >

led – allows to control the LEDs (Light Emitting Diodes) of the RouterBOARD 200 series embedded boards. This command is available only on RouterBoard 200 platform with the routerboard package installed

[admin@MikroTik] > :led led2=yes led3=yes length=5s

len – returns the number of characters in string or the number of elements in list depending on the type of the argument

[admin@MikroTik] > :put [:len gvejimezyfopmekun]
17
[admin@MikroTik] > :put [:len gve,jim,ezy,fop,mek,un]
6
[admin@MikroTik] >

list – displays a list of all available console commands that match given search key(s)

[admin@MikroTik] > :list user hotspot "add "
List of console commands under "/" matching "user" and "hotspot" and "add ":

ip hotspot profile add name= hotspot-address= dns-name= \
\... html-directory= rate-limit= http-proxy= smtp-server= \
\... login-by= http-cookie-lifetime= ssl-certificate= split-user-domain= \
\... use-radius= radius-accounting= radius-interim-update= copy-from=
ip hotspot user add server= name= password= address= mac-address= \
\... profile= routes= limit-uptime= limit-bytes-in= limit-bytes-out= \
\... copy-from= comment= disabled=
ip hotspot user profile add name= address-pool= session-timeout= \
\... idle-timeout= keepalive-timeout= status-autorefresh= \
\... shared-users= rate-limit= incoming-filter= outgoing-filter= \
\... incoming-mark= outgoing-mark= open-status-page= on-login= on-logout= copy-from=
[admin@MikroTik] >

local – declares local variable

[admin@MikroTik] > :local MyString "This is a string"
[admin@MikroTik] > :local IPAddr 10.0.0.1
[admin@MikroTik] > :local time   0:10
[admin@MikroTik] > :environment print
Global Variables
Local Variables
IPAddr=10.0.0.1
time=00:10:00
MyString=This is a string
[admin@MikroTik] >

log – adds a message specified by message parameter to the system logs.

[admin@MikroTik] > :log info "Very Good thing happened. We have received our first packet!"
[admin@MikroTik] > /log print follow
...
19:57:46 script,info Very Good thing happened. We have received our first packet!
...

nothing – has no action, and returns value of type “nothing”. In conditions nothing behaves as “false”

[admin@MikroTik] > :local string qwerty
[admin@MikroTik] > :if ([:pick $string 10]=[:nothing]) do={
{... :put "pick and nothing commands return the same value"}
pick and nothing commands return the same value
[admin@MikroTik] >

pick – returns a range of elements or a substring depending on the type of input value

[admin@MikroTik] > :set a 1,2,3,4,5,6,7,8
[admin@MikroTik] > :put [:len $a]
8
[admin@MikroTik] > :put [:pick $a]
1
[admin@MikroTik] > :put [:pick $a 0 4]
1,2,3,4
[admin@MikroTik] > :put [:pick $a 2 4]
3,4
[admin@MikroTik] > :put [:pick $a 2]
3
[admin@MikroTik] > :put [:pick $a 5 1000000]
6,7,8
[admin@MikroTik] > :set a abcdefghij
[admin@MikroTik] > :put [:len $a]
10
[admin@MikroTik] > :put [:pick $a]
a
[admin@MikroTik] > :put [:pick $a 0 4]
abcd
[admin@MikroTik] > :put [:pick $a 2 4]
cd
[admin@MikroTik] > :put [:pick $a 2]
c
[admin@MikroTik] > :put [:pick $a 5 1000000]
fghij

put – echoes supplied argument to the console

[admin@MikroTik] > :put [/interface get ether1 mtu]
1500
[admin@MikroTik] >

resolve – returns IP address of the host resolved from the DNS name. The DNS settings should be configured on the router (/ip dns submenu) prior to using this command.

[admin@MikroTik] ip route> /ip dns set primary-dns=159.148.60.2
[admin@MikroTik] ip route> :put [:resolve www.example.com]
192.0.34.166

set – assigns new value to a variable

[admin@MikroTik] > :put [:time [:resolve www.example.com ]]
00:00:00.006
[admin@MikroTik] >

time – measures the amount of time needed to execute given console commands

[admin@MikroTik] > :put [:time [:resolve www.example.com ]]
00:00:00.006
[admin@MikroTik] >

while – executes given console commands repeatedly while the logical conditions is true

[admin@MikroTik] > :set i 0; :while ($i < 10) do={:put $i; :set i ($i + 1)};
0
1
2
3
4
5
6
7
8
9
[admin@MikroTik] >

Special Commands

Description

Monitor

It is possible to access values that are shown by most monitor actions from scripts. A monitor command that has a do parameter can be supplied either script name (see /system scripts), or console commands to execute.

Get

Most print commands produce values that are accessible from scripts. Such print commands have a corresponding get command on the same menu level. The get command accepts one parameter when working with regular values or two parameters when working with lists.

Notes

Monitor command with do argument can also be called directly from scripts. It will not print anything then, just execute the given script.

The names of the properties that can be accessed by get are the same as shown by print command, plus names of item flags (like the disabled in the example below). You can use [T ab] key completions to see what properties any particular get action can return.

Example

In the example below monitor action will execute given script each time it prints stats on the screen, and it will assign all printed values to local variables with the same name:

[admin@MikroTik] interface> monitor-traffic ether2 once do={:environment print}
    received-packets-per-second: 0
       received-bits-per-second: 0bps
        sent-packets-per-second: 0
           sent-bits-per-second: 0bps

Global Variables
i=1
Local Variables
sent-bits-per-second=0
received-packets-per-second=0
received-bits-per-second=0
sent-packets-per-second=0
[admin@MikroTik] interface>

Additional Features

Description

To include comment in the console script prefix it with ‘#’. In a line of script that starts with ‘#’ all characters until the newline character are ignored.

To put multiple commands on a single line separate them with ‘;’. Console treats ‘;’ as the end of line in scripts.

Any of the {}[]“‘\$ characters should be escaped in a reqular string with ‘\’ character. Console takes any character following ‘\’ literally, without assigning any special meaning to it, except for such cases:

\a     bell (alarm), character code 7
\b     backspace, character code 8
\f     form feed, character code 12
\n     newline, character code 10
\r     carriage return, character code 13
\t     tabulation, character code 9
\v     vertical tabulation, character code 11
\_     space, character code 32

Note that ‘\’, followed by any amount of whitespace characters (spaces, newlines, carriage returns, tabulations), followed by newline is treated as a single whitespace, except inside quotes, where it is treated as nothing. This is used by console to break up long lines in scripts generated by export commands.

Script Repository

Submenu level: /system script

Description

All scripts are stored in the /system script menu along with some service information such as script name, script owner, number of times the script was executed and permissions for particular script.

It is also possible to start a script manually via /system script run command.

Property Description

last-started (time) – date and time when the script has been last invoked. The argument is shown only if the run-count!=0.owner (name; default: admin) – the name of the user who created the scriptpolicy (multiple choice: ftp | local | policy | read | reboot | ssh | telnet | test | web | write; default: reboot,read,write,policy,test) – the list of the policies applicable:

run-count (integer; default: 0) – script usage counter. This counter is incremented each time the script is executed. The counter will reset after reboot.source (text; default: “”) – the script source code itself

Command Description

run (name) – executes a given script

Notes

You cannot do more in scripts than you are allowed to do by your current user rights, that is, you cannot use disabled policies. For example, if there is a policy group in /user group which allows you ssh,local,telnet,read,write,policy,test,web and this group is assigned to your user name, then you cannot make a script that reboots the router.

Example

The following example is a script for writing message “Hello World!” to the info log:

[admin@MikroTik] system script> add name="log-test" source={:log info "Hello World!"}
[admin@MikroTik] system script> run log-test

[admin@MikroTik] system script> print
 0 name="log-test" owner="admin" policy=ftp,reboot,read,write,policy,test,winbox,password last-started=mar/20/2001 22:51:41
   run-count=1 source=:log info "Hello World!"
[admin@MikroTik] system script>

Task Management

Submenu level: /system script job

Description

This facility is used to manage the active or scheduled tasks.

Property Description

name (read-only: name) – the name of the script to be referenced when invoking itowner (text) – the name of the user who created the scriptsource (read-only: text) – the script source code itself

Example

[admin@MikroTik] system script> job print
  # SCRIPT  OWNER                   STARTED
  0 DelayeD admin                   dec/27/2003 11:17:33

[admin@MikroTik] system script>

You can cancel execution of a script by removing it from the job list

[admin@MikroTik] system script> job remove 0
[admin@MikroTik] system script> job print

[admin@MikroTik] system script>

Script Editor

Command name: /system script edit

Description

RouterOS console has a simple full-screen editor for scripts with support for multiline script writing.

Keyboard Shortcuts

Command Description

edit (name) – opens the script specified by the name argument in full-screen editor

Notes

All characters that are deleted by backspace, delete or Ctrl+k keys are accumulated in the buffer. Pressing any other key finishes adding to this buffer (Ctrl+y can paste it’s contents), and the next delete operation will replace it’s contents. Undo doesn’t change contents of cut buffer.

Script editor works only on VT102 compatible terminals (terminal names “vt102″, “linux”, “xterm”, “rxvt” are recognized as VT102 at the moment). Delete, backspace and cursor keys might not work with all terminal programs, use ‘Ctrl’ alternatives in such cases.

Example

The following example shows the script editor window with a sample script open:

This script is used for writing message “hello” and 3 messages “kuku” to the system log.

©

Bahasa Indonesia

Serial port monitoring utility monitors state of attached asynchronous serial ports and generates system events upon state change.

Specifications

Packages required: advanced-tools
License required: Level1
Submenu level: /tool sigwatch
Standards and Technologies: none
Hardware usage: Not significant

Related Documents

Sigwatch

Description

Sigwatch monitors state of the serial port pins.

Property Description

count (read-only: integer) – how many times the event for this item was triggered. Count is reset on reboot and on most item configuration changeslog (yes | no; default: no) – whether to add a message in form of name-of-sigwatch-item: signal changed [to high | to low] to System-Info facility whenever this sigwatch item is triggeredname (name) – name of the sigwatch itemon-condition (on | off | change; default: on) – on what condition to trigger action of this item

port (name) – serial port name to monitorscript (name) – script to execute when this item is trigeredsignal (dtr | rts | cts | dcd | ri | dsr; default: rts) – name of signal of number of pin (for standard 9-pin connector) to monitor

state (read-only: text) – last remembered state of monitored signal

Notes

You can type actual script source instead of the script name from /system script list.

Example

In the following example we will add a new sigwatch item that monitors whether the port serial1 has cts signal.

[admin@10.179] tool sigwatch> pr
Flags: X - disabled
  #   NAME                                  PORT    SIGNAL     ON-CONDITION LOG
  0   test                                  serial1 cts        change       no
[admin@MikroTik] tool sigwatch>

By typing a command print detail interval=1s, we can check whether a cable is connected or it is not. See the state argument – if the cable is connected to the serial port, it shows on, otherwise it will be off.

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=1 state=on

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=1 state=on

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=2 state=off

[admin@MikroTik] tool sigwatch> print detail
Flags: X - disabled
  0   name="test" port=serial1 signal=cts on-condition=change log=no script=""
      count=2 state=off

[admin@MikroTik] tool sigwatch>

In the port menu you can see what signal is used by serial cable. For example, without any cables it looks like this:

[admin@MikroTik] port> print stats
  0 name="serial0" line-state=dtr,rts

  1 name="serial1" line-state=dtr,rts
[admin@MikroTik] port>

But after adding a serial cable to the serial port:

[admin@MikroTik] port> print stats
  0 name="serial0" line-state=dtr,rts

  1 name="serial1" line-state=dtr,rts,cts
[admin@MikroTik] port>

This means that the line-state besides the dtr and rts signals has also cts when a serial cable is connected.

The example below will execute a script whenever on-condition changes to off:

[admin@10.MikroTik] tool sigwatch> pr detail
Flags: X - disabled
  0   name="cts_rest" port=serial1 signal=cts on-condition=off log=no
      script=/system shutdown count=0 state=on
[admin@10.MikroTik] tool sigwatch>

It means that if a serial cable is connected to the serial port, all works fine, but as soon as it is disconnected, the router shuts down. It will continue all the time until the serial cable will not be connected again.

©

Bahasa Indonesia

The Netwatch tool monitors network host by means of ping and generates events on status change.

Specifications

Packages required: system
License required: Level1
Submenu level: /tool netwatch
Standards and Technologies: None
Hardware usage: Not significant

Related Documents

Network Watching Tool

Specifications

Packages required: advanced-tools
License required: Level1
Submenu level: /tool netwatch
Standards and Technologies: none
Hardware usage: Not significant

Description

Netwatch monitors state of hosts on the network. It does so by sending ICMP pings to the 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 it’s ability to issue arbitrary console commands on host state changes.

Property Description

down-script (name) – a console script that is executed once when state of a host changes from unknown or up to down host (IP address; default: 0.0.0.0) – IP address of host that should be monitoredinterval (time; default: 1s) – the time between pings. Lowering this will make state changes more responsive, but can create unnecessary traffic and consume system resourcessince (read-only: time) – indicates when state of the host changed last timestatus (read-only: up | down | unknown) – shows the current status of the host

timeout (time; default: 1s) – timeout for each ping. If no reply from a host is received during this time, the host is considered unreachable (down)up-script (name) – a console script that is executed once when state of a host changes from unknown or down to up

Example

This example will run the scripts gw_1 or gw_2 which change the default gateway depending on the status of one of the gateways:

[admin@MikroTik] system script> add name=gw_1 source={/ip route set
{... [/ip route find dst 0.0.0.0] gateway 10.0.0.1}
[admin@MikroTik] system script> add name=gw_2 source={/ip route set
{.. [/ip route find dst 0.0.0.0] gateway 10.0.0.217}
[admin@MikroTik] system script> /tool netwatch
[admin@MikroTik] tool netwatch> add host=10.0.0.217 interval=10s timeout=998ms \
\... up-script=gw_2 down-script=gw_1
[admin@MikroTik] tool netwatch> print
Flags: X - disabled
  #   HOST	      TIMEOUT		   INTERVAL		STATUS
  0   10.0.0.217      997ms		   10s			up
[admin@MikroTik] tool netwatch> print detail
Flags: X - disabled
  0   host=10.0.0.217 timeout=997ms interval=10s since=feb/27/2003 14:01:03
      status=up up-script=gw_2 down-script=gw_1

[admin@MikroTik] tool netwatch>

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:

[admin@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 0.0.0.0. Usually, that is 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:

[admin@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 is another example, that sends e-mail notification whenever the 10.0.0.215 host goes down:

[admin@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"}
[admin@MikroTik] system script> 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"}
[admin@MikroTik] system script>
[admin@MikroTik] system script> /tool netwatch
[admin@MikroTik] system netwatch> add host=10.0.0.215 timeout=999ms \
\... interval=20s up-script=e-up down-script=e-down
[admin@MikroTik] tool netwatch> print detail
Flags: X - disabled
  0   host=10.0.0.215 timeout=998ms interval=20s since=feb/27/2003 14:15:36
      status=up up-script=e-up down-script=e-down

[admin@MikroTik] tool netwatch>

©

Bahasa Indonesia

Traceroute determines how packets are being routed to a particular host.

Specifications

Packages required: system
License required: Level1
Submenu level: /tool
Standards and Technologies: ICMP, UDP, Traceroute
Hardware usage: Not significant

Related Documents

Description

Traceroute is a TCP/IP protocol-based utility, which allows user to determine how packets are being routed to a particular host. Traceroute works by increasing the time-to-live value of packets and seeing how far they get until they reach the given destination; thus, a lengthening trail of hosts passed through is built up.

Traceroute shows the number of hops to the given host address of every passed gateway. Traceroute utility sends packets three times to each passed gateway so it shows three timeout values for each gateway in ms.

The Traceroute Command

Command name: /tool traceroute

Property Description

(IP address) – IP address of the host you are tracing route to port (integer: 0..65535) – UDP port number protocol (UDP | ICMP) – type of protocol to use. If one fails (for example, it is blocked by a firewall), try the other size (integer: 28..1500; default: 64) – packet size in bytes timeout (time: 1s..8s; default: 1s) – response waiting timeout, i.e. delay between messages tos (integer: 0..255; default: 0) – Type Of Service – parameter of IP packet use-dns (yes | no; default: no) – specifies whether to use DNS server, which can be set in /ip dns menu src-address (IP address) – change the source address of the packet max-hops (integer) – utmost hops through which packet can be reached

Notes

Traceroute session may be stopped by pressing [Ctrl]+[C].

Example

To trace the route to 216.239.39.101 host using ICMP protocol with packet size of 64 bytes, setting ToS field to 8 and extending the timeout to 4 seconds:

[admin@MikroTik] tool> traceroute 216.239.39.101 protocol=icmp size=64 tos=8 timeout=4s
     ADDRESS					STATUS
   1 159.148.60.227	  3ms	   3ms	    3ms
   2 195.13.173.221	 80ms	 169ms	   14ms
   3 195.13.173.28	  6ms	   4ms	    4ms
   4 195.158.240.21	111ms	 110ms	  110ms
   5 213.174.71.49	124ms	 120ms	  129ms
   6 213.174.71.134	139ms	 146ms	  135ms
   7 213.174.70.245	132ms	 131ms	  136ms
   8 213.174.70.58	211ms	 215ms	  215ms
   9 195.158.229.130	225ms	 239ms	     0s
  10 216.32.223.114	283ms	 269ms	  281ms
  11 216.32.132.14	267ms	 260ms	  266ms
  12 209.185.9.102	296ms	 296ms	  290ms
  13 216.109.66.1	288ms	 297ms	  294ms
  14 216.109.66.90	297ms	 317ms	  319ms
  15 216.239.47.66	137ms	 136ms	  134ms
  16 216.239.47.46	135ms	 134ms	  134ms
  17 216.239.39.101	134ms	 134ms	  135ms
[admin@MikroTik] tool>

©