The console is used for accessing the MikroTik Router's configuration and management features using text terminals, either remotely using serial port, telnet, SSH or console screen within Winbox, or directly using monitor and keyboard. The console is also used for writing scripts. This manual describes the general console operation principles. Please consult the Scripting Manual on some advanced console commands and on how to write scripts.
The console allows the configuration of the router's settings using text commands. Since there is a lot of available commands, they are split into groups organized in a way of hierarchical menu levels. The name of a menu level reflects the configuration information accessible in the relevant section, eg. /ip hotspot.
For example, you can issue the /ip route print command:
Instead of typing /ip route path before each command, the path can be typed only once to move into this particular branch of menu hierarchy. Thus, the example above could also be executed like this:
Notice that the prompt changes in order to reflect where you are located in the menu hierarchy at the moment. To move to the top level again, type " / "
To move up one command level, type " .. "
You can also use / and .. to execute commands from other menu levels without changing the current level:
Many of the command levels operate with arrays of items: interfaces, routes, users, etc. Such arrays are displayed in similarly looking lists. All items in the list have an item number followed by flags and parameter values.
To change properties of an item, you have to use set command and specify name or number of the item.
Some lists have items with specific names assigned to each of them. Examples are interface or user levels. There you can use item names instead of item numbers.
You do not have to use the print command before accessing items by their names, which, as opposed to numbers, are not assigned by the console internally, but are properties of the items. Thus, they would not change on their own. However, there are all kinds of obscure situations possible when several users are changing router's configuration at the same time. Generally, item names are more "stable" than the numbers, and also more informative, so you should prefer them to numbers when writing console scripts.
Item numbers are assigned by the print command and are not constant - it is possible that two successive print commands will order items differently. But the results of last print commands are memorized and, thus, once assigned, item numbers can be used even after add, remove and move operations (since version 3, move operation does not renumber items). Item numbers are assigned on a per session basis, they will remain the same until you quit the console or until the next print command is executed. Also, numbers are assigned separately for every item list, so the ip address print will not change the numbering of the interface list.
Since version 3 it is possible to use item numbers without running print command. Numbers will be assigned just as if the print command was executed.
You can specify multiple items as targets to some commands. Almost everywhere, where you can write the number of item, you can also write a list of numbers.
There are two features in the console that help entering commands much quicker and easier - the [Tab] key completions, and abbreviations of command names. Completions work similarly to the bash shell in UNIX. If you press the [Tab] key after a part of a word, the console tries to find the command within the current context that begins with this word. If there is only one match, it is automatically appended, followed by a space:
/inte[Tab]_ becomes /interface _
If there is more than one match, but they all have a common beginning, which is longer than that what you have typed, then the word is completed to this common part, and no space is appended:
/interface set e[Tab]_ becomes /interface set ether_
If you've typed just the common part, pressing the tab key once has no effect. However, pressing it for the second time shows all possible completions in compact form:
The [Tab] key can be used almost in any context where the console might have a clue about possible values - command names, argument names, arguments that have only several possible values (like names of items in some lists or name of protocol in firewall and NAT rules). You cannot complete numbers, IP addresses and similar values.
Another way to press fewer keys while typing is to abbreviate command and argument names. You can type only beginning of command name, and, if it is not ambiguous, console will accept it as a full name. So typing:
It is possible to complete not only the beginning, but also any distinctive substring of a name: if there is no exact match, the console starts looking for words that have string being completed as first letters of a multiple word name, or that simply contain letters of this string in the same order. If single such word is found, it is completed at cursor position. For example:
There are some commands that are common to nearly all menu levels, namely: print, set, remove, add, find, get, export, enable, disable, comment, move. These commands have similar behavior throughout different menu levels.
You can combine commands, here are two variants of the same command that will place a new firewall filter entry, by looking up comment:
/ip firewall/filter/add chain=forward place-before=[find where comment=CommentX]
/ip/firewall/filter/add chain=forward place-before="CommentX"
Console line editor works either in multiline mode or in single-line mode. In multiline mode line editor displays complete input line, even if it is longer than single terminal line. It also uses a full-screen editor for editing large text values, such as scripts. In single-line mode only one terminal line is used for line editing, and long lines are shown truncated around the cursor. A full-screen editor is not used in this mode.
Choice of modes depends on detected terminal capabilities.
Control-C keyboard interrupt. Control-D log out (if input line is empty)Control-K clear from cursor to the end of lineControl-X toggle safe modeControl-V toggle hotlock mode modeF6 toggle cellarF1 or ? show context sensitive help. If the previous character is \, then inserts literal ?.Tab perform line completion. When pressed second time, show possible completions.Delete remove character at cursorControl-H or Backspace remove character before cursor and move cursor back one position.Control-\ split line at cursor. Insert newline at cursor position. Display second of the two resulting lines.Control-B or Left move cursor backwards one characterControl-F or Right move cursor forward one characterControl-P or Up go to previous line. If this is the first line of input then recall previous input from history.Control-N or Down go to next line. If this is the last line of input then recall next input from history.Control-A or Home move cursor to the beginning of the line. If cursor is already at the beginning of the line, then go to the beginning of the first line of current input.Control-E or End move cursor to the end of line. If cursor is already at the end of line, then move it to the end of the last line of current input.Control-L or F5 reset terminal and repaint screen.
up, down and split keys leave cursor at the end of line.
The console has a built-in help, which can be accessed by typing ?. The general rule is that helps shows what you can type in a position where the ? was pressed (similarly to pressing [Tab] key twice, but in verbose form and with explanations).
It is sometimes possible to change router configuration in a way that will make the router inaccessible (except from local console). Usually this is done by accident, but there is no way to undo last change when connection to router is already cut. Safe mode can be used to minimize such risk.
Safe mode is entered by pressing [CTRL]+[X]. To save changes and quit safe mode, press [CTRL]+[X] again. To exit without saving the made changes, hit [CTRL]+[D]
Message Safe Mode taken is displayed and prompt changes to reflect that session is now in safe mode. All configuration changes that are made (also from other login sessions), while router is in safe mode, are automatically undone if safe mode session terminates abnormally. You can see all such changes that will be automatically undone tagged with an F flag in system history:
Now, if telnet connection (or winbox terminal) is cut, then after a while (TCP timeout is 9 minutes) all changes that were made while in safe mode will be undone. Exiting session by [Ctrl]+[D] also undoes all safe mode changes, while /quit does not.
If another user tries to enter safe mode, he's given following message:
If too many changes are made while in safe mode, and there's no room in history to hold them all (currently history keeps up to 100 most recent actions), then session is automatically put out of the safe mode, no changes are automatically undone. Thus, it is best to change configuration in small steps, while in safe mode. Pressing [Ctrl]+[X] twice is an easy way to empty safe mode action list.
When HotLock mode is enabled commands will be auto-completed.
To enter/exit HotLock mode press [CTRL]+[V].
>>is an indication that HotLock mode is enabled. For example, if you type
/in e, it will be auto-completed to
F6 key enables a menu at the bottom of the terminal which shows common key combinations and their usage.