479 lines
19 KiB
Plaintext
479 lines
19 KiB
Plaintext
[[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.
|