Having the expert mode flag stored in the global 'host' structure
was a bad idea, because this way it applies globally. In other
words, if user Bob activates the expert mode in his dedicated
session (e.g. a telnet connection), then not only him, but all
other users would see the hidden commands in their VTYs.
Moreover, if somebody deactivates the expert mode, it would also
affect the Bob's VTY session. And finally, terminating a VTY
session would not deactivate the expert mode.
Let's move that flag from the global 'struct host' to 'struct vty'
representing an individual VTY session, so then the expert mode
would only affect the session where it was activated.
In functions related to the XML VTY reference generation we don't
have access to 'struct vty' (there may be no VTY session at all).
Add two additional arguments to vty_dump_nodes(), indicating the
global flag mask and a matching mode. This would allow to match
the VTY commands in many different ways, e.g. one can dump hidden
commands only, or all commands except the library specific ones.
Change-Id: Iba13f0949061e3dadf9cf92829d15e97074fe4ad
Related: SYS#4910
This change introduces an enumerated type 'vty_ref_gen_mode' that
(as the name suggests) defines the VTY reference generation mode:
- DEFAULT - all commands except deprecated and hidden,
- EXPERT - all commands including hidden, excluding deprecated;
and a new function vty_dump_xml_ref_mode(), that allows to specify
that mode. The old vty_dump_xml_ref() is now deprecated.
Change-Id: Ie2022a7f9e167e5ceacf15350c037dd43768ff40
Related: SYS#4910
Some VTY commands are intentionally hidden, e.g. because they might
by relatively dangerous if used in production operation. We equip
such commands with a special attribute - CMD_ATTR_HIDDEN.
The problem is that neiter they appear in the XML VTY reference,
nor in the online VTY help, so it's a bit tricky to invoke them.
This change introduces so-called 'expert' mode, in which hidden
(but not deprecated) commands are getting visible.
In the (telnet) VTY session, this mode can be activated by passing
an additional argument to well-known 'enable' command:
OsmoApp> enable ?
[expert-mode] Enable the expert mode (show hidden commands)
OsmoApp> enable expert-mode
OsmoApp#
so then hidden commands will appear together with all the other
commands. They will be marked with a special '^' flag:
OsmoApp# list with-flags
^ ... foo-hidden [expert-mode]
. ... foo-regular-one
! ... foo-immediate
^ u.. app-hidden-unbelievable
For the XML reference generation, additional API needs to be
introduced. This will be implemented in subsequent patches.
Change-Id: Ie69c2a19b22fb31d7bd7f6412f0aeac86ea5048f
Related: SYS#4910
This new attribute would allow to distinguish commands provided
by libraries from commands registered by the application itself,
so vty_dump_element() would print proper description for the
library specific attributes.
All VTY commands defined by the libraries need to use the new API:
- install_lib_element(), and
- install_lib_element_ve,
instead of the old functions (respectively):
- install_element(), and
- install_element_ve().
See https://lists.osmocom.org/pipermail/openbsc/2020-October/013278.html.
Change-Id: I8baf31ace93c536421893c2aa4e3d9d298dcbcc6
Related: SYS#4937
Process willing to support this kind of configuration through VTY simply
need to call "osmo_sched_vty_init(tall_ctx);" during startup to register
the commands.
For multithreaded processes, new threads willing to get their
cpu-affinity mask according to VTY config should call
osmo_sched_vty_apply_localthread() (potentially after
setting the thread name through pthread_setname_np()).
Related: SYS#4986
Change-Id: If76a4bd2cc7b3c7adf5d84790a944d78be70e10a
Allow dumping the VTY XML reference (for generating manuals) to a normal FILE*
stream instead of a vty output buffer.
We currently generate the VTY reference by starting the client program,
connecting to the VTY telnet and dumping the reference. That is weirdly
convoluted, especially since there has to be a valid config file that
successfully starts up a minimal set of external links before the reference can
be generated. IMO we should have dumped the XML reference to stdout from the
start, and never to a VTY session.
With this patch, it is trivial to generate the XML VTY reference by a
commandline switch. The client program will set up the entire VTY, and
immediately after parsing the cmdline options but before parsing a config file,
just dumps the reference and doesn't even start establishing local ports. That
would allow generating the XML reference on the fly during the build process of
the manuals, without the need of a docker container or somesuch.
A first implementation of such a commandline switch is `osmo-bsc -X`, added in
I316efedb2c1652791434ecf14a1e261367cd2fb7
This patch jumps through a bit of a hoop to still allow dumping to a VTY buffer
without code dup, to still allow dumping the XML reference through telnet VTY,
until all our programs have implemented an -X switch (TM).
Change-Id: Ic74bbdb6dc5ea05f03c791cc70184861e39cd492
Some osmo-* applications may need to use their own VTY node as a
parent for the timer configuration commands. Therefore it makes
more sense to use 'unsigned int' instead of 'enum node_type'.
Let's also clarify that osmo_tdef_vty_groups_init() accepts parent
node for configuration commands only: 'parent_node' -> 'parent_cfg_node'.
Change-Id: Ifb4c406c85d76a25fc53fc235484599aa87dc77c
Although this OSMO_DEPRECATED doesn't seem to generate a warning when compiling
code that sets .is_config_node = foo, it seems a good idea to add the
deprecation tag.
It is deprecated since commit "vty: track parent nodes also for telnet sessions"
I2b32b4fe20732728db6e9cdac7e484d96ab86dc5
Change-Id: I800507b27cb0d536c1a4c203d7f7b90eec05a69c
Keep track of parent nodes and go back hierarchically, not only for .cfg file
reading, but also for telnet VTY sessions.
A long time ago cfg file parsing was made strictly hierarchical: node exits go
back to parent nodes exactly as they were entered. However, live telnet VTY
sessions still lacked this and depended on the go_parent_cb().
From this commit on, implementing a go_parent_cb() is completely optional. The
go_parent_cb() no longer has the task to determine the correct parent node,
neither for cfg files (as already the case before this patch) nor for telnet
VTY sessions (added by this patch). Instead, a go_parent_cb() implementation
can merely take actions it requires on node exits, for example applying some
config when leaving a specific node.
The node value that is returned by the go_parent_cb() and the vty->node and
vty->index values that might be set are completely ignored; instead the
implicit parent node tracking determines the parent and node object.
As a side effect, the is_config_node() callback is no longer needed, since the
VTY now always implicitly knows when to exit back to the CONFIG_NODE.
For example, osmo_ss7_is_config_node() could now be dropped, and the
osmo_ss7_vty_go_parent() could be shortened by five switch cases, does no
longer need to set vty->node nor vty->index and could thus be shortened to:
int osmo_ss7_vty_go_parent(struct vty *vty)
{
struct osmo_ss7_asp *asp;
struct osmo_xua_server *oxs;
switch (vty->node) {
case L_CS7_ASP_NODE:
asp = vty->index;
/* If no local addr was set */
if (!asp->cfg.local.host_cnt) {
asp->cfg.local.host[0] = NULL;
asp->cfg.local.host_cnt = 1;
}
osmo_ss7_asp_restart(asp);
break;
case L_CS7_XUA_NODE:
oxs = vty->index;
/* If no local addr was set, or erased after _create(): */
if (!oxs->cfg.local.host_cnt)
osmo_ss7_xua_server_set_local_host(oxs, NULL);
if (osmo_ss7_xua_server_bind(oxs) < 0)
vty_out(vty, "%% Unable to bind xUA server to IP(s)%s", VTY_NEWLINE);
break;
}
return 0;
}
Before parent tracking, every program was required to write a go_parent_cb()
which has to return every node's parent node, basically a switch() statement
that manually traces the way back out of child nodes. If the go_parent_cb() has
errors, we may wildly jump around the node tree: a common error is to jump
right out to the top config node with one exit, even though we were N levels
deep. This kind of error has been eliminated for cfg files long ago, but still
exists for telnet VTY sessions, which this patch fixes.
This came up when I was adding multi-level config nodes to osmo-hlr to support
Distributed GSM / remote MS lookup: the config file worked fine, while vty node
tests failed to exit to the correct nodes.
Change-Id: I2b32b4fe20732728db6e9cdac7e484d96ab86dc5
libosmo{core,gsm,vty} code is GPLv2+. The tdef code originated in
osmo-msc.git and was moved here without changing the license. That
was a mistake, it always was meant to be under GPLv2-or-later after
moving to libosmocore.git.
Copyright is with sysmocom, so I as the managing director can
approve the license change.
Change-Id: Ie483ff6f6ea0a56c477649677b4b163c49df11d7
For async callbacks it is useful to determine whether a given VTY pointer is still valid.
For example, in osmo-msc, a silent call can be triggered by VTY, which causes a
Paging. The paging_cb then writes to the VTY console that the silent call has
succeeded. Unless the telnet vty session has already ended, in which case
osmo-msc crashes; e.g. from an osmo_interact_vty.py command invocation. With
this function, osmo-msc can ask whether the vty pointer passed to the paging
callback is still active, and skip vty_out() if not.
Change-Id: I42cf2af47283dd42c101faae0fac293c3a68d599
fi->T values are int, i.e. can be negative. Do not log them as unsigned, but
define a distinct timer class "Xnnnn" for negative T values: i.e. for T == -1,
print "Timeout of X1" instead of "Timeout of T4294967295".
The negative T timer number space is useful to distinguish freely invented
timers from proper 3GPP defined T numbers. So far I was using numbers like
T993210 or T9999 for invented T, but X1, X2 etc. is a better solution. This way
we can make sure to not accidentally define an invented timer number that
actually collides with a proper 3GPP specified timer number that the author was
not aware of at the time of writing.
Add OSMO_T_FMT and OSMO_T_FMT_ARGS() macros as standardized timer number print
format. Use that in fsm.c, tdef_vty.c, and adjust vty tests accordingly.
Mention the two timer classes in various API docs and VTY online-docs.
Change-Id: I3a59457623da9309fbbda235fe18fadd1636bff6
Move T_def from osmo-bsc to libosmocore as osmo_tdef. Adjust naming to be more
consistent. Upgrade to first class API:
- add timer grouping
- add generic vty support
- add mising API doc
- add C test
- add VTY transcript tests, also as examples for using the API
From osmo_fsm_inst_state_chg() API doc, cross reference to osmo_tdef API.
The root reason for moving to libosmocore is that I want to use the
mgw_endpoint_fsm in osmo-msc for inter-MSC handover, and hence want to move the
FSM to libosmo-mgcp-client. This FSM uses the T_def from osmo-bsc. Though the
mgw_endpoint_fsm's use of T_def is minimal, I intend to use the osmo_tdef API
in osmo-msc (and probably elsewhere) as well. libosmocore is the most sensible
place for this.
osmo_tdef provides:
- a list of Tnnnn (GSM) timers with description, unit and default value.
- vty UI to allow users to configure non-default timeouts.
- API to tie T timers to osmo_fsm states and set them on state transitions.
- a few standard units (minute, second, millisecond) as well as a custom unit
(which relies on the timer's human readable description to indicate the
meaning of the value).
- conversion for standard units: for example, some GSM timers are defined in
minutes, while our FSM definitions need timeouts in seconds. Conversion is
for convenience only and can be easily avoided via the custom unit.
By keeping separate osmo_tdef arrays, several groups of timers can be kept
separately. The VTY tests in tests/tdef/ showcase different schemes:
- tests/vty/tdef_vty_test_config_root.c:
Keep several timer definitions in separately named groups: showcase the
osmo_tdef_vty_groups*() API. Each timer group exists exactly once.
- tests/vty/tdef_vty_test_config_subnode.c:
Keep a single list of timers without separate grouping.
Put this list on a specific subnode below the CONFIG_NODE.
There could be several separate subnodes with timers like this, i.e.
continuing from this example, sets timers could be separated by placing
timers in specific config subnodes instead of using the global group name.
- tests/vty/tdef_vty_test_dynamic.c:
Dynamically allocate timer definitions per each new created object.
Thus there can be an arbitrary number of independent timer definitions, one
per allocated object.
T_def was introduced during the recent osmo-bsc refactoring for inter-BSC
handover, and has proven useful:
- without osmo_tdef, each invocation of osmo_fsm_inst_state_chg() needs to be
programmed with the right timeout value, for all code paths that invoke this
state change. It is a likely source of errors to get one of them wrong. By
defining a T timer exactly for an FSM state, the caller can merely invoke the
state change and trust on the original state definition to apply the correct
timeout.
- it is helpful to have a standardized config file UI to provide user
configurable timeouts, instead of inventing new VTY commands for each
separate application of T timer numbers.
Change-Id: Ibd6b1ed7f1bd6e1f2e0fde53352055a4468f23e5
Provide a va_list type vty_out() variant, to be able to pass on variable
arguments from other function signatures to vty_out().
This will be used by Ibd6b1ed7f1bd6e1f2e0fde53352055a4468f23e5 for osmo_tdef.
Change-Id: Ie6e6f11a6b794f3cb686350c1ed678e4d5bbbb75
Extend the vty_bind_cmd VTY command to allow to optionally specify
a port in addition to the IPv4 address.
Introduce telnet_init_default to relieve client code from having
to query the bind IPv4 address (and now the TCP port). Instead a
client only needs to pass the default TCP port to use.
Client code should use it like:
int rc = telnet_init_default(ctx, priv, OSMO_VTY_PORT_SGSN);
Change-Id: Id5fb2faaf4311bd7284ee870526a6f87b7e260f3
Since the CMD_ATTR_* flags are intended to be used in bitwise
operations, let's assign them proper values. Adding a new flag
(e.g. CMD_ATTR_FOO_BAR) could actually result in assigning 0x03
instead of expected (0x01 << 2).
Change-Id: I3b1badef830f7e6436a67673b5709ec33c060c68
Related: OS#3584
This function permits the user to register deprecated log categories,
which will ensure that if log categories are removed from a program,
old config files will still load.
We simply dynamically allocate a cmd_element and install it at
CFG_LOG_NODE. Not registering it at VIEW_NODE or ENABLE_NODE
ensures that it's not accessible from the interactive VTY, but only
from the config file / configure node.
Change-Id: I171f62ea2dc565b3a6c3eecd27fb7853e2529598
This new function can be used to print a rate counter group according
to a format string. The intention is to generalize and replace manual
printing of counters as implemented for the 'show statistics' VTY
command of osmo-bsc.
Related: OS#3245
Related: osmo-bsc commit 71d524c059c5a5c90e7cb77d8a2134c1c68b9cde (g#9217)
Change-Id: Idb3ec12494ff6a3a05efcc8818e78d1baa6546bd
So far it uses 2323, a development default. Instead, assign new ports,
appending to the common range of VTY and CTRL ports: 4261 and 4262.
Related: https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
Related: I28bd7a97d24455f88fadc6724d45c3264ba2fce4 (osmo-gsm-manuals)
Change-Id: Ife52a968a41cb286f640006587877971ff66c1a4
It was decided that osmo-mgw as direct successor of osmo-bsc_mgcp
will use the same VTY port number (similar to osmo-nitb, osmo-bsc
and osmo-bsc-sccplite all using the same VTY port number)
Change-Id: Iec1da9f3b4d170416279f05876d9e1ae2970c577
Following I5021c64a787b63314e0f2f1cba0b8fc7bff4f09b a deprecation of
vty_install_default() and install_default() commands is indicated.
However, compiler warnings may clutter build output or even fail strict builds,
hence I am submitting the deprecation in a separate patch.
Depends: I5021c64a787b63314e0f2f1cba0b8fc7bff4f09b
Change-Id: Icf5d83f641e838cebcccc635a043e94ba352abff
In many callers of the VTY API, we are lacking the vty_install_default() step
at certain node levels. This creates nodes that lack the 'exit' command, and
hence the only way to exit such a node is to restart the telnet session.
Historically, the VTY looked for missing commands on the immediate parent node,
and hence possibly found the parent's 'exit' command when the local node was
missing it. That is why we so far did not notice the missing default commands.
Furthermore, some callers call install_default() instead of
vty_install_default(). Only vty_install_default() also includes the 'exit' and
'end' commands. There is no reason why there are two sets of default commands.
To end this confusion, to catch all missing 'exit' commands and to prevent this
from re-appearing in the future, simply *always* install all default commands
implicitly when calling install_node().
In cmd_init(), there are some top-level nodes that apparently do not want the
default commands installed. Keep those the way they are, by changing the
invocation to new install_node_bare() ({VIEW,AUTH,AUTH_ENABLE}_NODE).
Make both install_default() and vty_install_default() no-ops so that users of
the API may still call them without harm. Do not yet deprecate yet, which
follows in Icf5d83f641e838cebcccc635a043e94ba352abff.
Drop all invocations to these two functions found in libosmocore.
Change-Id: I5021c64a787b63314e0f2f1cba0b8fc7bff4f09b
This change introduces a new command, which could be used to
inspect the application's talloc context directly from VTY.
To enable this feature, an application need to provide it's
context via the 'vty_app_info' struct, and register the VTY
command by calling the osmo_talloc_vty_add_cmds().
The new command is a sub-command of 'show':
show talloc-context <context> <depth> [filter]
Currently the following contexts may be inspected:
- application - a context provided by an application;
- null - all contexts, if NULL-context tracking is enabled.
A report depth is defined by the next parameter, and could be:
- full - full tree report, as the talloc_report_full() does;
- brief - brief tree report, as the talloc_report() does;
- DEPTH - user defined maximal report depth.
Also, there are two optional report filters:
- regexp - print only contexts, matching a regular expression;
- tree - print a specific context, pointed by specified address.
The command output is formatted the same way as in case of calling
the talloc_report() or talloc_report_full().
Change-Id: I43fc42880b22294d83c565ae600ac65e4f38b30d
The 'show online-help' produces XML output with <node id="..."> ids. We
reference those from the osmo-gsm-manuals.
Instead of numeric IDs coming from internal code, rather use a human-readable
node ID -- referencing id='config-msc' is much easier than referencing id='23'.
Add a char name[] to struct cmd_node, to hold this name. This may be provided
upon struct definition.
Since callers of the VTY API so far don't have a name yet, we would need to add
names everywhere to get meaningful node IDs. There is a way to get node ID
names without touching dependent code:
My first idea was to find out which command entered the node, i.e. command
'msc' enters the MSC_NODE. But it is impossible to derive which command entered
which node from data structs, it's hidden in the vty command definition.
But in fact all (TM) known API callers indeed provide a prompt string that
contains a logical and human readable string name. Thus, if the name is unset
in the struct, parse the prompt string and strip all "weird" characters to
obtain a node name from that. We can still set names later on, but for now will
have meaningful node IDs (e.g. 'config-msc' from '%s(config-msc)# ') without
touching any dependent code.
When VTY nodes get identical node names, which is quite possible, the XML
export de-dups these by appending _2, _3,... suffixes. The first occurence is
called e.g. 'name', the second 'name_2', then 'name_3', and so forth.
If a node has no name (even after parsing the prompt), it will be named merely
by the suffix. The first empty node will become id='_1', then '_2', '_3', and
so forth. This happens for nodes like VIEW_NODE or AUTH_NODE.
If this is merged, we need to adjust the references in osmo-gsm-manuals.git.
This can happen in our own time though, because we manually create the vty
reference xml and copy it to the osmo-gsm-manuals.git and then update the
references from the vty_additions.xml. This anyway has to happen because
currently the references tend to be hopelessly out of sync anyway, placing
comments at wildly unrelated VTY commands.
Change-Id: I8fa555570268b231c5e01727c661da92fad265de
Note: This will break users' config files if they do not use consistent
indenting. (see below for a definition of "consistent".)
When reading VTY commands from a file, use indenting as means to implicitly
exit child nodes. Do not look for commands in the parent node implicitly.
The VTY so far implies 'exit' commands if a VTY line cannot be parsed on the
current node, but succeeds on the parent node. That is the mechanism by which
our VTY config files do not need 'exit' at the end of each child node.
We've hit problems with this in the following scenarios, which will show
improved user experience after this patch:
*) When both a parent and its child node have commands with identical names:
cs7 instace 0
point-code 1.2.3
sccp-address osmo-msc
point-code 0.0.1
If I put the parent's command below the child, it is still interpreted in the
context of the child node:
cs7 instace 0
sccp-address osmo-msc
point-code 0.0.1
point-code 1.2.3
Though the indenting lets me assume I am setting the cs7 instance's global PC
to 1.2.3, I'm actually overwriting osmo-msc's PC with 1.2.3 and discarding the
0.0.1.
*) When a software change moves a VTY command from a child to a parent. Say
'timezone' moved from 'bts' to 'network' level:
network
timezone 1 2
Say a user still has an old config file with 'timezone' on the child level:
network
bts 0
timezone 1 2
trx 0
The user would expect an error message that 'timezone' is invalid on the 'bts'
level. Instead, the VTY finds the parent node's 'timezone', steps out of 'bts'
to the 'network' level, and instead says that the 'trx' command does not exist.
Format:
Consistent means that two adjacent indenting lines have the exact
same indenting characters for the common length:
Weird mix if you ask me, but correct and consistent:
ROOT
<space>PARENT
<space><tab><space>CHILD
<space><tab><space><tab><tab>GRANDCHILD
<space><tab><space><tab><tab>GRANDCHILD2
<space>SIBLING
Inconsistent:
ROOT
<space>PARENT
<tab><space>CHILD
<space><space><tab>GRANDCHILD
<space><tab><tab>GRANDCHILD2
<tab>SIBLING
Also, when going back to a parent level, the exact same indenting must be used
as before in that node:
Incorrect:
ROOT
<tab>PARENT
<tab><tab><tab>CHILD
<tab><tab>SIBLING
As not really intended side effect, it is also permitted to indent the entire
file starting from the root level. We could guard against it but there's no
harm:
Correct and consistent:
<tab>ROOT
<tab><tab>PARENT
<tab><tab><tab><tab>CHILD
<tab><tab>SIBLING
Implementation:
Track parent nodes state: whenever a command enters a child node, push a parent
node onto an llist to remember the exact indentation characters used for that
level.
As soon as the first line on a child node is parsed, remember this new
indentation (which must have a longer strlen() than its parent level) to apply
to all remaining child siblings and grandchildren.
If the amount of spaces that indent a following VTY command are less than this
expected indentation, call vty_go_parent() until it matches up.
At any level, if the common length of indentation characters mismatch, abort
parsing in error.
Transitions to child node are spread across VTY implementations and are hard to
change. But transitions to the parent node are all handled by vty_go_parent().
By popping a parent from the list of parents in vty_go_parent(), we can also
detect that a command has changed the node without changing the parent, hence
it must have stepped into a child node, and we can push a parent frame.
The behavior on the interactive telnet VTY remains unchanged.
Change-Id: I24cbb3f6de111f2d31110c3c484c066f1153aac9
Considering the various styles and implications found in the sources, edit
scores of files to follow the same API doc guidelines around the doxygen
grouping and the \file tag.
Many files now show a short description in the generated API doc that was so
far only available as C comment.
The guidelines and reasoning behind it is documented at
https://osmocom.org/projects/cellular-infrastructure/wiki/Guidelines_for_API_documentation
In some instances, remove file comments and add to the corresponding group
instead, to be shared among several files (e.g. bitvec).
Change-Id: Ifa70e77e90462b5eb2b0457c70fd25275910c72b
Especially for short descriptions, it is annoying to have to type \brief for
every single API doc.
Drop all \brief and enable the AUTOBRIEF feature of doxygen, which always takes
the first sentence of an API doc as the brief description.
Change-Id: I11a8a821b065a128108641a2a63fb5a2b1916e87
Harald Welte
Alexander Couzens
Vadim Yanitskiy
Philipp Maier
Pau Espin
Daniel Willmann
Neels Hofmeyr