path: root/common/chapters/vty.adoc

[[vty]]
== 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
argument values.

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
<<vty-ref-osmomsc>>.

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
[options="header",cols="35%,25%,40%"]
|===============
|Pattern|Example|Explanation
|`A.B.C.D`|`127.0.0.1`|An IPv4 address
|`A.B.C.D/M`|`192.168.1.0/24`|An IPv4 address and mask
|`X:X::X:X`|`::1`|An IPv6 address
|`X:X::X:X/M`|`::1/128`|An IPv6 address and mask
|`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.

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
connect 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:

VIEW::
  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.

ENABLE::
  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.

CONFIG::
  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
  suffix.
  +
  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.

Other::
  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 OsmoMSC 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
command.

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 OsmoMSC prompt
----
OsmoMSC> <1>
  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 logging
  no          Negate a command or set its defaults
  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
----
OsmoMSC> show <1>
  version          Displays program version
  online-help      Online help
  history          Display the session command history
  cs7              ITU-T Signaling System 7
  logging          Show current logging configuration
  alarms           Show current logging configuration
  talloc-context   Show talloc memory hierarchy
  stats            Show statistical values
  asciidoc         Asciidoc generation
  rate-counters    Show all rate counters
  fsm              Show information about finite state machines
  fsm-instances    Show information about finite state machine instances
  sgs-connections  Show SGs interface connections / MMEs
  subscriber       Operations on a Subscriber
  bsc              BSC
  connection       Subscriber Connections
  transaction      Transactions
  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 `bsc` object and type `?` again:

.Example: Typing `?` after `show bsc`
----
OsmoMSC> show bsc
  <cr>
----

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
choice.

.Example: Use of `<tab>` pressed after typing only `s` as command
----
OsmoMSC> s<1>
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
----
OsmoMSC> show <1>
version    online-help history    cs7        logging    alarms
talloc-context stats      asciidoc   rate-counters fsm        fsm-instances
sgs-connections subscriber bsc        connection transaction statistics
sms-queue smpp
----
<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 OsmoMSC 'VIEW' node prompt
----
OsmoMSC> list
  show version
  show online-help
  list
  exit
  help
  enable
  terminal length <0-512>
  terminal no length
  who
  show history
  show cs7 instance <0-15> users
  show cs7 (sua|m3ua|ipa) [<0-65534>]
  show cs7 instance <0-15> asp
  show cs7 instance <0-15> as (active|all|m3ua|sua)
  show cs7 instance <0-15> sccp addressbook
  show cs7 instance <0-15> sccp users
  show cs7 instance <0-15> sccp ssn <0-65535>
  show cs7 instance <0-15> sccp connections
  show cs7 instance <0-15> sccp timers
  logging enable
  logging disable
  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 print category-hex (0|1)
  logging print level (0|1)
  logging print file (0|1|basename) [last]
  logging set-log-mask MASK
  logging level (rll|cc|mm|rr|mncc|pag|msc|mgcp|ho|db|ref|ctrl|smpp|ranap|vlr|iucs|bssap|sgs|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)
  logging level set-all (debug|info|notice|error|fatal)
  logging level force-all (debug|info|notice|error|fatal)
  no logging level force-all
  show logging vty
  show alarms
  show talloc-context (application|all) (full|brief|DEPTH)
  show talloc-context (application|all) (full|brief|DEPTH) tree ADDRESS
  show talloc-context (application|all) (full|brief|DEPTH) filter REGEXP
  show stats
  show stats level (global|peer|subscriber)
  show asciidoc counters
  show rate-counters
  show fsm NAME
  show fsm all
  show fsm-instances NAME
  show fsm-instances all
  show sgs-connections
  show subscriber (msisdn|extension|imsi|tmsi|id) ID
  show subscriber cache
  show bsc
  show connection
  show transaction
  sms send pending
  sms delete expired
  subscriber create imsi ID
  subscriber (msisdn|extension|imsi|tmsi|id) ID sms sender (msisdn|extension|imsi|tmsi|id) SENDER_ID send .LINE
  subscriber (msisdn|extension|imsi|tmsi|id) ID silent-sms sender (msisdn|extension|imsi|tmsi|id) SENDER_ID send .LINE
  subscriber (msisdn|extension|imsi|tmsi|id) ID silent-call start (any|tch/f|tch/any|sdcch)
  subscriber (msisdn|extension|imsi|tmsi|id) ID silent-call stop
  subscriber (msisdn|extension|imsi|tmsi|id) ID ussd-notify (0|1|2) .TEXT
  subscriber (msisdn|extension|imsi|tmsi|id) ID ms-test close-loop (a|b|c|d|e|f|i)
  subscriber (msisdn|extension|imsi|tmsi|id) ID ms-test open-loop
  subscriber (msisdn|extension|imsi|tmsi|id) ID paging
  show statistics
  show sms-queue
  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 OsmoMSC 'VIEW'
node with the list of the OsmoMSC 'NETWORK' config node:

.Example: Typing `list` at start of OsmoMSC 'NETWORK' config node prompt
----
OsmoMSC(config-net)# list
  help
  list
  write terminal
  write file
  write memory
  write
  show running-config
  exit
  end
  network country code <1-999>
  mobile network code <0-999>
  short name NAME
  long name NAME
  encryption a5 <0-3> [<0-3>] [<0-3>] [<0-3>]
  authentication (optional|required)
  rrlp mode (none|ms-based|ms-preferred|ass-preferred)
  mm info (0|1)
  timezone <-19-19> (0|15|30|45)
  timezone <-19-19> (0|15|30|45) <0-2>
  no timezone
  periodic location update <6-1530>
  no periodic location update
----

==== The attribute system

The VTY allows to edit the configuration at runtime. For many VTY commands the
configuration change is immediately valid but for some commands a change becomes
valid on a certain event only. In some cases it is even necessary to restart the
whole process.

To give the user an overview, which configuration change applies when, the VTY
implemets a system of attribute flags, which can be displayed using the `show`
command with the parameter `vty-attributes`

.Example: Typing `show vty-attributes` at the VTY prompt
----
OsmoBSC> show vty-attributes
  Global attributes:
    ^  This command is hidden (check expert mode)
    !  This command applies immediately
    @  This command applies on VTY node exit
  Library specific attributes:
    A  This command applies on ASP restart
    I  This command applies on IPA link establishment
    L  This command applies on E1 line update
  Application specific attributes:
    o  This command applies on A-bis OML link (re)establishment
    r  This command applies on A-bis RSL link (re)establishment
    l  This command applies for newly created lchans
----

The attributes are symbolized through a single ASCII letter (flag) and do exist
in three levels. This is more or less due to the technical aspects of the VTY
implementation. For the user, the level of an attribute has only informative
purpose.

The global attributes, which can be found under the same attribute letter in every
osmocom application, exist on the top level. The Library specific attributes below
are used in various osmocom libraries. Like with the global attributes the attribute
flag letter stays the same throughout every osmocom application here as well. On
the third level one can find the application specific attributes. Those are unique
to each osmocom application and the attribute letters may have different meanings
in different osmocom applications. To make the user more aware of this, lowercase
letters were used as attribute flags.

The `list` command with the parameter `with-flags` displays a list of available
commands on the current VTY node, along with attribute columns on the left side.
Those columns contain the attribute flag letters to indicate to the user how the
command behaves in terms of how and when the configuration change takes effect.

.Example: Typing `list with-flags` at the VTY prompt
----
OsmoBSC(config-net-bts)# list with-flags
  . ...  help
  . ...  list [with-flags]
  . ...  show vty-attributes
  . ...  show vty-attributes (application|library|global)
  . ...  write terminal
  . ...  write file [PATH]
  . ...  write memory
  . ...  write
  . ...  show running-config <1>
  . ...  exit
  . ...  end
  . o..  type (unknown|bs11|nanobts|rbs2000|nokia_site|sysmobts) <2>
  . ...  description .TEXT
  . ...  no description
  . o..  band BAND
  . .r.  cell_identity <0-65535> <3>
  . .r.  dtx uplink [force]
  . .r.  dtx downlink
  . .r.  no dtx uplink
  . .r.  no dtx downlink
  . .r.  location_area_code <0-65535>
  . o..  base_station_id_code <0-63>
  . o..  ipa unit-id <0-65534> <0-255>
  . o..  ipa rsl-ip A.B.C.D
  . o..  nokia_site skip-reset (0|1)
  ! ...  nokia_site no-local-rel-conf (0|1) <4>
  ! ...  nokia_site bts-reset-timer  <15-100> <4>
----
<1> This command has no attributes assigned.
<2> This command applies on A-bis OML link (re)establishment.
<3> This command applies on A-bis RSL link (re)establishment.
<4> This command applies immediately.

There are multiple columns because a single command may be associated with
multiple attributes at the same time. To improve readability each flag letter
gets a dedicated column. Empty spaces in the column are marked with a dot (".")

In some cases the listing will contain commands that are associated with no
flags at all. Those commands either play an exceptional role (interactive
commands outside "configure terminal", vty node navigation commands, commands
to show / write the config file) or will require a full restart of the overall
process to take effect.

==== The expert mode

Some VTY commands are considered relatively dangerous if used in production operation,
so the general approach is to hide them. This means that they don't show up anywhere
but the source code, but can still be executed. On the one hand, this approach reduces
the risk of an accidental invocation and potential service degradation; on the other,
it complicates intentional use of the hidden commands.

The VTY features so-called __expert__ mode, that makes the hidden commands appear in
the interactive help, as well as in the XML VTY reference, just like normal ones. This
mode can be activated from the 'VIEW' node by invoking the `enable` command with the
parameter `expert-mode`. It remains active for the individual VTY session, and gets
disabled automatically when the user switches back to the 'VIEW' node or terminates
the session.

A special attribute in the output of the `list with-flags` command indicates whether
a given command is hidden in normal mode, or is a regular command:

.Example: Hidden commands in the output of the `list with-flags` command
----
OsmoBSC> enable expert-mode <1>
OsmoBSC# list with-flags
  ...
  ^   bts <0-255> (activate-all-lchan|deactivate-all-lchan) <2>
  ^   bts <0-255> trx <0-255> (activate-all-lchan|deactivate-all-lchan) <2>
  .   bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> mdcx A.B.C.D <0-65535> <3>
  ^   bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> (borken|unused) <2>
  .   bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> handover <0-255> <3>
  .   bts <0-255> trx <0-255> timeslot <0-7> sub-slot <0-7> assignment <3>
  .   bts <0-255> smscb-command (normal|schedule|default) <1-4> HEXSTRING <3>
  ...
----
<1> This command enables the __expert__ mode.
<2> This is a hidden command (only shown in the __expert__ mode).
<3> This is a regular command that is always shown regardless of the mode.