== The Osmocom VTY Interface
All human interaction with Osmocom software is typically performed via an
interactive command-line interface called the _VTY_.
NOTE: Integration of your programs and scripts should *not* be done via the
telnet VTY interface, which is intended for human interaction only: the VTY
responses may arbitrarily change in ways obvious to humans, while your scripts'
parsing will likely break often. For external software to interact with Osmocom
programs (besides using the dedicated protocols), it is strongly recommended to
use the Control interface instead of the VTY, and to actively request /
implement the Control interface commands as required for your use case.
The interactive telnet VTY is used to
* explore the current status of the system, including its configuration
parameters, but also to view run-time state and statistics,
* review the currently active (running) configuration,
* perform interactive changes to the configuration (for those items that do not
require a program restart),
* store the current running configuration to the config file,
* enable or disable logging; to the VTY itself or to other targets.
The Virtual Tele Type (VTY) has the concept of __nodes__ and
__commands__. Each command has a name and arguments. The name may
contain a space to group several similar commands into a specific group.
The arguments can be a single word, a string, numbers, ranges or a list
of options. The available commands depend on the current node. there
are various keyboard shortcuts to ease finding commands and the possible
Configuration file parsing during program start is actually performed the VTY's
CONFIG node, which is also available in the telnet VTY. Apart from that, the
telnet VTY features various interactive commands to query and instruct a
running Osmocom program. A main difference is that during config file parsing,
consistent indenting of parent vs. child nodes is required, while the
interactive VTY ignores indenting and relies on the 'exit' command to return to
a parent node.
NOTE: In the 'CONFIG' node, it is not well documented which commands take
immediate effect without requiring a program restart. To save your current
config with changes you may have made, you may use the `write file` command to
*overwrite* your config file with the current configuration, after which you
should be able to restart the program with all changes taking effect.
This chapter explains most of the common nodes and commands. A more detailed
list is available in various programs' VTY reference manuals, e.g. see
There are common patterns for the parameters, these include IPv4
addresses, number ranges, a word, a line of text and choice. The
following will explain the commonly used syntactical patterns:
.VTY Parameter Patterns
|`A.B.C.D`|`127.0.0.1`|An IPv4 address
|`TEXT`|`example01`|A single string without any spaces, tabs
|`.TEXT`|`Some information`|A line of text
|`(OptionA\|OptionB\|OptionC)`|`OptionA`|A choice between a list of available options
|`<0-10>`|`5`|A number from a range
=== Accessing the telnet VTY
The VTY of a given Osmocom program is implemented as a telnet server,
listening to a specific TCP port. For `osmo-nitb`, this port is `4242`.
Please see <<port-numbers>> to check for the default TCP port number of
the VTY interface of the specific Osmocom software you would like to
As telnet is insecure and offers neither strong authentication nor
encryption, the VTY by default only binds to localhost (127.0.0.1) and
will thus not be reachable by other hosts on the network.
WARNING: By default, any user with access to the machine running the
Osmocom software will be able to connect to the VTY. We assume that
such systems are single-user systems, and anyone with local access to
the system also is authorized to access the VTY. If you require
stronger security, you may consider using the packet filter of your
operating system to restrict access to the Osmocom VTY ports further.
=== VTY Nodes
The VTY by default has the following minimal nodes:
When connecting to a telnet VTY, you will be on the 'VIEW' node.
As its name implies, it can only be used to view the system
status, but it does not provide commands to alter the system
state or configuration. As long as you are in the non-privileged
'VIEW' node, your prompt will end in a `>` character.
The 'ENABLE' node is entered by the `enable` command,
from the 'VIEW' node. Changing into the 'ENABLE' node will unlock all
kinds of commands that allow you to alter the system state or perform
any other change to it. The 'ENABLE' node and its children are
signified by a '#' character at the end of your prompt.
You can change back from the 'ENABLE' node to the 'VIEW' node by using
the `disable` command.
The 'CONFIG' node is entered by the `configure terminal`
command from the 'ENABLE' node. The config node is used to change the
run-time configuration parameters of the system. The prompt will
indicate that you are in the config node by a `(config)#` prompt
You can always leave the 'CONFIG' node or any of its children by using
the `end` command.
This node is also automatically entered at the time the configuration
file is read. All configuration file lines are processed as if they
were entered from the VTY 'CONFIG' node at start-up.
Depending on the specific Osmocom program you are running, there will
be few or more other nodes, typically below the 'CONFIG' node. For
example, the OsmoBSC has nodes for each BTS, and within the BTS node
one for each TRX, and within the TRX node one for each Timeslot.
=== Interactive help
The VTY features an interactive help system, designed to help you to
efficiently navigate is commands.
NOTE: The VTY is present on most Osmocom GSM/UMTS/GPRS software, thus this
chapter is present in all the relevant manuals. The detailed examples
below assume you are executing them on the OsmoNITB VTY. They will work
in similar fashion on the other VTY interfaces, while the node structure will
differ in each program.
==== The question-mark (`?`) command
If you type a single `?` at the prompt, the VTY will display
possible completions at the exact location of your currently entered
If you type `?` at an otherwise empty command (without having entered
even only a partial command), you will get a list of the first word of
all possible commands available at this node:
.Example: Typing `?` at start of OsmoNITB prompt
show Show running system information
list Print command list
exit Exit current mode and down to previous mode
help Description of the interactive help system
enable Turn on privileged mode command
terminal Set terminal line parameters
who Display who is on vty
logging Configure log message to this terminal
sms SMS related commands
subscriber Operations on a Subscriber
<1> Type `?` here at the prompt, the `?` itself will not be printed.
If you have already entered a partial command, `?` will help you to
review possible options of how to continue the command. Let's say you
remember that `show` is used to investigate the system status, but you
don't remember the exact name of the object. Hitting `?` after typing `show`
will help out:
.Example: Typing `?` after a partial command
OpenBSC> show <1>
version Displays program version
online-help Online help
history Display the session command history
network Display information about a GSM NETWORK
bts Display information about a BTS
trx Display information about a TRX
timeslot Display information about a TS
lchan Display information about a logical channel
paging Display information about paging requests of a BTS
paging-group Display the paging group
logging Show current logging configuration
alarms Show current logging configuration
stats Show statistical values
e1_driver Display information about available E1 drivers
e1_line Display information about a E1 line
e1_timeslot Display information about a E1 timeslot
subscriber Operations on a Subscriber
statistics Display network statistics
sms-queue Display SMSqueue statistics
smpp SMPP Interface
<1> Type `?` after the `show` command, the `?` itself will not be printed.
You may pick the `network` object and type `?` again:
.Example: Typing `?` after `show network`
OpenBSC> show network
By presenting `<cr>` as the only option, the VTY tells you that your command is
complete without any remaining arguments being available, and that you should
hit enter, a.k.a. "carriage return".
==== TAB completion
The VTY supports tab (tabulator) completion. Simply type any partial
command and press `<tab>`, and it will either show you a list of
possible expansions, or completes the command if there's only one
.Example: Use of `<tab>` pressed after typing only `s` as command
show sms subscriber
<1> Type `<tab>` here.
At this point, you may choose `show`, and then press `<tab>` again:
.Example: Use of `<tab>` pressed after typing `show` command
OpenBSC> show <1>
version online-help history network bts trx
timeslot lchan paging paging-group logging alarms
stats e1_driver e1_line e1_timeslot subscriber statistics
<1> Type `<tab>` here.
==== The `list` command
The `list` command will give you a full list of all commands and their
arguments available at the current node:
.Example: Typing `list` at start of OsmoNITB 'VIEW' node prompt
terminal length <0-512>
terminal no length
show bts [<0-255>]
show trx [<0-255>] [<0-255>]
show timeslot [<0-255>] [<0-255>] [<0-7>]
show lchan [<0-255>] [<0-255>] [<0-7>] [lchan_nr]
show lchan summary [<0-255>] [<0-255>] [<0-7>] [lchan_nr]
show paging [<0-255>]
show paging-group <0-255> IMSI
logging filter all (0|1)
logging color (0|1)
logging timestamp (0|1)
logging print extended-timestamp (0|1)
logging print category (0|1)
logging set-log-mask MASK
logging level (all|rll|cc|mm|rr|rsl|nm|mncc|pag|meas|sccp|msc|mgcp|ho|db|ref|gprs|ns|bssgp|llc|sndcp|nat|ctrl|smpp|filter|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats) (debug|info|notice|error|fatal)
show logging vty
show stats level (global|peer|subscriber)
show e1_line [line_nr] [stats]
show e1_timeslot [line_nr] [ts_nr]
show subscriber (extension|imsi|tmsi|id) ID
show subscriber cache
sms send pending
subscriber create imsi ID
subscriber (extension|imsi|tmsi|id) ID sms sender (extension|imsi|tmsi|id) SENDER_ID send .LINE
subscriber (extension|imsi|tmsi|id) ID silent-sms sender (extension|imsi|tmsi|id) SENDER_ID send .LINE
subscriber (extension|imsi|tmsi|id) ID silent-call start (any|tch/f|tch/any|sdcch)
subscriber (extension|imsi|tmsi|id) ID silent-call stop
subscriber (extension|imsi|tmsi|id) ID ussd-notify (0|1|2) .TEXT
subscriber (extension|imsi|tmsi|id) ID update
logging filter imsi IMSI
show smpp esme
TIP: Remember, the list of available commands will change significantly
depending on the Osmocom program you are accessing, its software version and
the current node you're at. Compare the above example of the OsmoNITB 'VIEW'
node with the list of the OsmoNITB 'TRX' config node:
.Example: Typing `list` at start of OsmoNITB 'TRX' config node prompt
nominal power <0-100>
rsl e1 line E1_LINE timeslot <1-31> sub-slot (0|1|2|3|full)
rsl e1 tei <0-63>