Retrofitting Configuration Commands
Retrofitting process
This page explains how to convert existing CLI configuration commands to the new northbound model. This documentation is meant to be the primary reference for developers working on the northbound retrofitting process. We’ll show several examples taken from the ripd northbound conversion to illustrate some concepts described herein.
Step 1: writing a YANG module
The first step is to write a YANG module that models faithfully the commands that are going to be converted. As explained in the [[Architecture]] page, the goal is to introduce the new YANG-based Northbound API without introducing backward incompatible changes in the CLI. The northbound retrofitting process should be completely transparent to FRR users.
The developer is free to choose whether to write a full YANG module or a partial YANG module and increment it gradually. For developers who lack experience with YANG it’s probably a better idea to model one command at time.
It’s recommended to reuse definitions from standard YANG models whenever possible to facilitate the process of writing module translators using the [[YANG module translator]]. As an example, the frr-ripd YANG module incorporated several parts of the IETF RIP YANG module. The repositories below contain big collections of YANG models that might be used as a reference:
When writing a YANG module, it’s highly recommended to follow the guidelines from RFC 6087. In general, most commands should be modeled fairly easy. Here are a few guidelines specific to authors of FRR YANG models:
Use presence-containers or lists to model commands that change the CLI node (e.g.
router rip,interface eth0). This way, if the presence-container or list entry is removed, all configuration options below them are removed automatically (exactly like the CLI behaves when a configuration object is removed using a no command). This recommendation is orthogonal to the YANG authoring guidelines for OpenConfig models where the use of presence containers is discouraged. OpenConfig YANG models however were not designed to replicate the behavior of legacy CLI commands.When using YANG lists, be careful to identify what should be the key leaves. In the
offset-list WORD <in|out> (0-16) IFNAMEcommand, for example, both the direction (<in|out>) and the interface name should be the keys of the list. This can be only known by analyzing the data structures used to store the commands.For clarity, use non-presence containers to group leaves that are associated to the same configuration command (as we’ll see later, this also facilitate the process of writing
cli_showcallbacks).YANG leaves of type enumeration should define explicitly the value of each enum option based on the value used in the FRR source code.
Default values should be taken from the source code whenever they exist.
Some commands are more difficult to model and demand the use of more advanced YANG constructs like choice, when and must statements. One key requirement is that it should be impossible to load an invalid JSON/XML configuration to FRR. The YANG modules should model exactly what the CLI accepts in the form of commands, and all restrictions imposed by the CLI should be defined in the YANG models whenever possible. As we’ll see later, not all constraints can be expressed using the YANG language and sometimes we’ll need to resort to code-level validation in the northbound callbacks.
Tip: the Yang Tools page details several tools and commands that might be useful when writing a YANG module, like validating YANG files, indenting YANG files, validating instance data, etc.
In the example YANG snippet below, we can see the use of the must statement that prevents ripd from redistributing RIP routes into itself. Although ripd CLI doesn’t allow the operator to enter redistribute rip under router rip, we don’t have the same protection when configuring ripd using other northbound interfaces (e.g. NETCONF). So without this constraint it would be possible to feed an invalid configuration to ripd (i.e. a bug).
list redistribute {
key "protocol";
description
"Redistributes routes learned from other routing protocols.";
leaf protocol {
type frr-route-types:frr-route-types-v4;
description
"Routing protocol.";
must '. != "rip"';
}
[snip]
}
In the example below, we use the YANG choice statement to ensure that
either the password leaf or the key-chain leaf is configured,
but not both. This is in accordance to the sanity checks performed by
the ip rip authentication commands.
choice authentication-data {
description
"Choose whether to use a simple password or a key-chain.";
leaf authentication-password {
type string {
length "1..16";
}
description
"Authentication string.";
}
leaf authentication-key-chain {
type string;
description
"Key-chain name.";
}
}
Once finished, the new YANG model should be put into the FRR yang/ top
level directory. This will ensure it will be installed automatically by
make install. It’s also encouraged (but not required) to put sample
configurations under yang/examples/ using either JSON or XML files.
Step 2: generate skeleton northbound callbacks
Use the gen_northbound_callbacks tool to generate skeleton callbacks for the YANG module. Example:
$ tools/gen_northbound_callbacks frr-ripd > ripd/rip_northbound.c
The tool will look for the given module in the YANG_MODELS_PATH
directory defined during the installation. For each schema node of the
YANG module, the tool will generate skeleton callbacks based on the
properties of the node. Example:
/*
* XPath: /frr-ripd:ripd/instance
*/
static int ripd_instance_create(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
/* TODO: implement me. */
return NB_OK;
}
static int ripd_instance_delete(enum nb_event event,
const struct lyd_node *dnode)
{
/* TODO: implement me. */
return NB_OK;
}
/*
* XPath: /frr-ripd:ripd/instance/allow-ecmp
*/
static int ripd_instance_allow_ecmp_modify(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
/* TODO: implement me. */
return NB_OK;
}
[snip]
const struct frr_yang_module_info frr_ripd_info = {
.name = "frr-ripd",
.nodes = {
{
.xpath = "/frr-ripd:ripd/instance",
.cbs.create = ripd_instance_create,
.cbs.delete = ripd_instance_delete,
},
{
.xpath = "/frr-ripd:ripd/instance/allow-ecmp",
.cbs.modify = ripd_instance_allow_ecmp_modify,
},
[snip]
{
.xpath = "/frr-ripd:ripd/state/routes/route",
.cbs.get_next = ripd_state_routes_route_get_next,
.cbs.get_keys = ripd_state_routes_route_get_keys,
.cbs.lookup_entry = ripd_state_routes_route_lookup_entry,
},
{
.xpath = "/frr-ripd:ripd/state/routes/route/prefix",
.cbs.get_elem = ripd_state_routes_route_prefix_get_elem,
},
{
.xpath = "/frr-ripd:ripd/state/routes/route/next-hop",
.cbs.get_elem = ripd_state_routes_route_next_hop_get_elem,
},
{
.xpath = "/frr-ripd:ripd/state/routes/route/interface",
.cbs.get_elem = ripd_state_routes_route_interface_get_elem,
},
{
.xpath = "/frr-ripd:ripd/state/routes/route/metric",
.cbs.get_elem = ripd_state_routes_route_metric_get_elem,
},
{
.xpath = "/frr-ripd:clear-rip-route",
.cbs.rpc = clear_rip_route_rpc,
},
[snip]
After the C source file is generated, it’s necessary to add a copyright
header on it and indent the code using clang-format.
Step 3: update the frr_yang_module_info array of all relevant daemons
We must inform the northbound about which daemons will implement the new
YANG module. This is done by updating the frr_daemon_info structure
of these daemons, with help of the FRR_DAEMON_INFO macro.
When a YANG module is specific to a single daemon, like the frr-ripd module, then only the corresponding daemon should be updated. When the YANG module is related to a subset of libfrr (e.g. route-maps), then all FRR daemons that make use of that subset must be updated.
Example:
static const struct frr_yang_module_info *ripd_yang_modules[] = {
&frr_interface_info,
&frr_ripd_info,
};
FRR_DAEMON_INFO(ripd, RIP, .vty_port = RIP_VTY_PORT,
[snip]
.yang_modules = ripd_yang_modules,
.n_yang_modules = array_size(ripd_yang_modules), )
Step 4: implement the northbound configuration callbacks
Implementing the northbound configuration callbacks consists mostly of copying code from the corresponding CLI commands and make the required adaptations.
It’s recommended to convert one command or a small group of related commands per commit. Small commits are preferred to facilitate the review process. Both “old” and “new” command can coexist without problems, so the retrofitting process can happen gradually over time.
The configuration callbacks
These are the four main northbound configuration callbacks, as defined
in the lib/northbound.h file:
/*
* Configuration callback.
*
* A presence container, list entry, leaf-list entry or leaf of type
* empty has been created.
*
* For presence-containers and list entries, the callback is supposed to
* initialize the default values of its children (if any) from the YANG
* models.
*
* event
* The transaction phase. Refer to the documentation comments of
* nb_event for more details.
*
* dnode
* libyang data node that is being created.
*
* resource
* Pointer to store resource(s) allocated during the NB_EV_PREPARE
* phase. The same pointer can be used during the NB_EV_ABORT and
* NB_EV_APPLY phases to either release or make use of the allocated
* resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
*
* Returns:
* - NB_OK on success.
* - NB_ERR_VALIDATION when a validation error occurred.
* - NB_ERR_RESOURCE when the callback failed to allocate a resource.
* - NB_ERR_INCONSISTENCY when an inconsistency was detected.
* - NB_ERR for other errors.
*/
int (*create)(enum nb_event event, const struct lyd_node *dnode,
union nb_resource *resource);
/*
* Configuration callback.
*
* The value of a leaf has been modified.
*
* List keys don't need to implement this callback. When a list key is
* modified, the northbound treats this as if the list was deleted and a
* new one created with the updated key value.
*
* event
* The transaction phase. Refer to the documentation comments of
* nb_event for more details.
*
* dnode
* libyang data node that is being modified
*
* resource
* Pointer to store resource(s) allocated during the NB_EV_PREPARE
* phase. The same pointer can be used during the NB_EV_ABORT and
* NB_EV_APPLY phases to either release or make use of the allocated
* resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
*
* Returns:
* - NB_OK on success.
* - NB_ERR_VALIDATION when a validation error occurred.
* - NB_ERR_RESOURCE when the callback failed to allocate a resource.
* - NB_ERR_INCONSISTENCY when an inconsistency was detected.
* - NB_ERR for other errors.
*/
int (*modify)(enum nb_event event, const struct lyd_node *dnode,
union nb_resource *resource);
/*
* Configuration callback.
*
* A presence container, list entry, leaf-list entry or optional leaf
* has been deleted.
*
* The callback is supposed to delete the entire configuration object,
* including its children when they exist.
*
* event
* The transaction phase. Refer to the documentation comments of
* nb_event for more details.
*
* dnode
* libyang data node that is being deleted.
*
* Returns:
* - NB_OK on success.
* - NB_ERR_VALIDATION when a validation error occurred.
* - NB_ERR_INCONSISTENCY when an inconsistency was detected.
* - NB_ERR for other errors.
*/
int (*delete)(enum nb_event event, const struct lyd_node *dnode);
/*
* Configuration callback.
*
* A list entry or leaf-list entry has been moved. Only applicable when
* the "ordered-by user" statement is present.
*
* event
* The transaction phase. Refer to the documentation comments of
* nb_event for more details.
*
* dnode
* libyang data node that is being moved.
*
* Returns:
* - NB_OK on success.
* - NB_ERR_VALIDATION when a validation error occurred.
* - NB_ERR_INCONSISTENCY when an inconsistency was detected.
* - NB_ERR for other errors.
*/
int (*move)(enum nb_event event, const struct lyd_node *dnode);
Since skeleton northbound callbacks are generated automatically by the gen_northbound_callbacks tool, the developer doesn’t need to worry about which callbacks need to be implemented.
NOTE: once a daemon starts, it reads its YANG modules and validates that all required northbound callbacks were implemented. If any northbound callback is missing, an error is logged and the program exists.
Transaction phases
Configuration transactions and their phases were described in detail in
the [[Architecture]] page. Here’s the definition of the nb_event
enumeration as defined in the lib/northbound.h file:
/* Northbound events. */
enum nb_event {
/*
* The configuration callback is supposed to verify that the changes are
* valid and can be applied.
*/
NB_EV_VALIDATE,
/*
* The configuration callback is supposed to prepare all resources
* required to apply the changes.
*/
NB_EV_PREPARE,
/*
* Transaction has failed, the configuration callback needs to release
* all resources previously allocated.
*/
NB_EV_ABORT,
/*
* The configuration changes need to be applied. The changes can't be
* rejected at this point (errors are logged and ignored).
*/
NB_EV_APPLY,
};
When converting a CLI command, we must identify all error-prone
operations and perform them in the NB_EV_PREPARE phase of the
northbound callbacks. When the operation in question involves the
allocation of a specific resource (e.g. file descriptors), we can store
the allocated resource in the resource variable given to the
callback. This way the allocated resource can be obtained in the other
phases of the transaction using the same parameter.
Here’s the create northbound callback associated to the
router rip command:
/*
* XPath: /frr-ripd:ripd/instance
*/
static int ripd_instance_create(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
int socket;
switch (event) {
case NB_EV_VALIDATE:
break;
case NB_EV_PREPARE:
socket = rip_create_socket();
if (socket < 0)
return NB_ERR_RESOURCE;
resource->fd = socket;
break;
case NB_EV_ABORT:
socket = resource->fd;
close(socket);
break;
case NB_EV_APPLY:
socket = resource->fd;
rip_create(socket);
break;
}
return NB_OK;
}
Note that the socket creation is an error-prone operation since it
depends on the underlying operating system, so the socket must be
created during the NB_EV_PREPARE phase and stored in
resource->fd. This socket is then either closed or used depending on
the outcome of the preparation phase of the whole transaction.
During the NB_EV_VALIDATE phase, the northbound callbacks must
validate if the intended changes are valid. As an example, FRR doesn’t
allow the operator to deconfigure active interfaces:
static int lib_interface_delete(enum nb_event event,
const struct lyd_node *dnode)
{
struct interface *ifp;
ifp = yang_dnode_get_entry(dnode);
switch (event) {
case NB_EV_VALIDATE:
if (CHECK_FLAG(ifp->status, ZEBRA_INTERFACE_ACTIVE)) {
zlog_warn("%s: only inactive interfaces can be deleted",
__func__);
return NB_ERR_VALIDATION;
}
break;
case NB_EV_PREPARE:
case NB_EV_ABORT:
break;
case NB_EV_APPLY:
if_delete(ifp);
break;
}
return NB_OK;
}
Note however that it’s preferred to use YANG to model the validation constraints whenever possible. Code-level validations should be used only to validate constraints that can’t be modeled using the YANG language.
Most callbacks don’t need to perform any validations nor perform any
error-prone operations, so in these cases we can use the following
pattern to return early if event is different than NB_EV_APPLY:
/*
* XPath: /frr-ripd:ripd/instance/distance/default
*/
static int ripd_instance_distance_default_modify(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
if (event != NB_EV_APPLY)
return NB_OK;
rip->distance = yang_dnode_get_uint8(dnode, NULL);
return NB_OK;
}
During development it’s recommend to use the debug northbound command to debug configuration transactions and see what callbacks are being called. Example:
ripd# conf t
ripd(config)# debug northbound
ripd(config)# router rip
ripd(config-router)# allow-ecmp
ripd(config-router)# network eth0
ripd(config-router)# redistribute ospf metric 2
ripd(config-router)# commit
% Configuration committed successfully.
ripd(config-router)#
Now the ripd log:
2018/09/23 12:43:59 RIP: northbound callback: event [validate] op [create] xpath [/frr-ripd:ripd/instance] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [validate] op [modify] xpath [/frr-ripd:ripd/instance/allow-ecmp] value [true]
2018/09/23 12:43:59 RIP: northbound callback: event [validate] op [create] xpath [/frr-ripd:ripd/instance/interface[.='eth0']] value [eth0]
2018/09/23 12:43:59 RIP: northbound callback: event [validate] op [create] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [validate] op [modify] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']/metric] value [2]
2018/09/23 12:43:59 RIP: northbound callback: event [prepare] op [create] xpath [/frr-ripd:ripd/instance] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [prepare] op [modify] xpath [/frr-ripd:ripd/instance/allow-ecmp] value [true]
2018/09/23 12:43:59 RIP: northbound callback: event [prepare] op [create] xpath [/frr-ripd:ripd/instance/interface[.='eth0']] value [eth0]
2018/09/23 12:43:59 RIP: northbound callback: event [prepare] op [create] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [prepare] op [modify] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']/metric] value [2]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [create] xpath [/frr-ripd:ripd/instance] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [modify] xpath [/frr-ripd:ripd/instance/allow-ecmp] value [true]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [create] xpath [/frr-ripd:ripd/instance/interface[.='eth0']] value [eth0]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [create] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']] value [(none)]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [modify] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']/metric] value [2]
2018/09/23 12:43:59 RIP: northbound callback: event [apply] op [apply_finish] xpath [/frr-ripd:ripd/instance/redistribute[protocol='ospf']] value [(null)]
Getting the data
One parameter that is common to all northbound configuration callbacks
is the dnode parameter. This is a libyang data node structure that
contains information relative to the configuration change that is being
performed. For create callbacks, it contains the configuration node
that is being added. For delete callbacks, it contains the
configuration node that is being deleted. For modify callbacks, it
contains the configuration node that is being modified.
In order to get the actual data value out of the dnode variable, we
need to use the yang_dnode_get_*() wrappers documented in
lib/yang_wrappers.h.
The advantage of passing a dnode structure to the northbound
callbacks is that the whole candidate being committed is made available,
so the callbacks can obtain values from other portions of the
configuration if necessary. This can be done by providing an xpath
expression to the second parameter of the yang_dnode_get_*()
wrappers to specify the element we want to get. The example below shows
a callback that gets the values of two leaves that are part of the same
list entry:
static int
ripd_instance_redistribute_metric_modify(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
int type;
uint8_t metric;
if (event != NB_EV_APPLY)
return NB_OK;
type = yang_dnode_get_enum(dnode, "../protocol");
metric = yang_dnode_get_uint8(dnode, NULL);
rip->route_map[type].metric_config = true;
rip->route_map[type].metric = metric;
rip_redistribute_conf_update(type);
return NB_OK;
}
NOTE: if the wrong
yang_dnode_get_*()wrapper is used, the code will log an error and abort. An example would be usingyang_dnode_get_enum()to get the value of a boolean data node.
No need to check if the configuration value has changed
A common pattern in CLI commands is this:
DEFUN (...)
{
[snip]
if (new_value == old_value)
return CMD_SUCCESS;
[snip]
}
Several commands need to check if the new value entered by the user is the same as the one currently configured. Then, if yes, ignore the command since nothing was changed.
The northbound callbacks on the other hand don’t need to perform this check since they act on effective configuration changes. Using the CLI as an example, if the operator enters the same command multiple times, the northbound layer will detect that nothing has changed in the configuration and will avoid calling the northbound callbacks unnecessarily.
In some cases, however, it might be desirable to check for inconsistencies and notify the northbound when that happens:
/*
* XPath: /frr-ripd:ripd/instance/interface
*/
static int ripd_instance_interface_create(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
const char *ifname;
if (event != NB_EV_APPLY)
return NB_OK;
ifname = yang_dnode_get_string(dnode, NULL);
return rip_enable_if_add(ifname);
}
/* Add interface to rip_enable_if. */
int rip_enable_if_add(const char *ifname)
{
int ret;
ret = rip_enable_if_lookup(ifname);
if (ret >= 0)
return NB_ERR_INCONSISTENCY;
vector_set(rip_enable_interface,
XSTRDUP(MTYPE_RIP_INTERFACE_STRING, ifname));
rip_enable_apply_all(); /* TODOVJ */
return NB_OK;
}
In the example above, the rip_enable_if_add() function should never
return NB_ERR_INCONSISTENCY in normal conditions. This is because
the northbound layer guarantees that the same interface will never be
added more than once (except when it’s removed and re-added again). But
to be on the safe side it’s probably wise to check for internal
inconsistencies to ensure everything is working as expected.
Default values
Whenever creating a new presence-container or list entry, it’s usually
necessary to initialize certain variables to their default values. FRR
most of the time uses special constants for that purpose
(e.g. RIP_DEFAULT_METRIC_DEFAULT, DFLT_BGP_HOLDTIME, etc). Now
that we have YANG models, we want to fetch the default values from these
models instead. This will allow us to changes default values smoothly
without needing to touch the code. Better yet, it will allow users to
create YANG deviations to define custom default values easily.
To fetch default values from the loaded YANG models, use the
yang_get_default_*() wrapper functions
(e.g. yang_get_default_bool()) documented in lib/yang_wrappers.h.
Example:
int rip_create(int socket)
{
rip = XCALLOC(MTYPE_RIP, sizeof(struct rip));
/* Set initial values. */
rip->ecmp = yang_get_default_bool("%s/allow-ecmp", RIP_INSTANCE);
rip->default_metric =
yang_get_default_uint8("%s/default-metric", RIP_INSTANCE);
[snip]
}
Configuration options are edited individually
Several CLI commands edit multiple configuration options at the same time. Some examples taken from ripd:
timers basic (5-2147483647) (5-2147483647) (5-2147483647)* /frr-ripd:ripd/instance/timers/flush-interval * /frr-ripd:ripd/instance/timers/holddown-interval * /frr-ripd:ripd/instance/timers/update-intervaldistance (1-255) A.B.C.D/M [WORD]* /frr-ripd:ripd/instance/distance/source/prefix * /frr-ripd:ripd/instance/distance/source/distance * /frr-ripd:ripd/instance/distance/source/access-list
In the new northbound model, there’s one or more separate callbacks for
each configuration option. This usually has implications when converting
code from CLI commands to the northbound commands. An example of this is
the following commit from ripd:
7cf2f2eaf.
The rip_distance_set() and rip_distance_unset() functions were
torn apart and their code split into a few different callbacks.
For lists and presence-containers, it’s possible to use the
yang_dnode_set_entry() function to attach user data to a libyang
data node, and then retrieve this value in the other callbacks (for the
same node or any of its children) using the yang_dnode_get_entry()
function. Example:
static int ripd_instance_distance_source_create(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
struct prefix_ipv4 prefix;
struct route_node *rn;
if (event != NB_EV_APPLY)
return NB_OK;
yang_dnode_get_ipv4p(&prefix, dnode, "./prefix");
/* Get RIP distance node. */
rn = route_node_get(rip_distance_table, (struct prefix *)&prefix);
rn->info = rip_distance_new();
yang_dnode_set_entry(dnode, rn);
return NB_OK;
}
static int
ripd_instance_distance_source_distance_modify(enum nb_event event,
const struct lyd_node *dnode,
union nb_resource *resource)
{
struct route_node *rn;
uint8_t distance;
struct rip_distance *rdistance;
if (event != NB_EV_APPLY)
return NB_OK;
/* Set distance value. */
rn = yang_dnode_get_entry(dnode);
distance = yang_dnode_get_uint8(dnode, NULL);
rdistance = rn->info;
rdistance->distance = distance;
return NB_OK;
}
Commands that edit multiple configuration options at the same time can
also use the apply_finish optional callback, documented as follows
in the lib/northbound.h file:
/*
* Optional configuration callback for YANG lists and containers.
*
* The 'apply_finish' callbacks are called after all other callbacks
* during the apply phase (NB_EV_APPLY). These callbacks are called only
* under one of the following two cases:
* * The container or a list entry has been created;
* * Any change is made within the descendants of the list entry or
* container (e.g. a child leaf was modified, created or deleted).
*
* This callback is useful in the cases where a single event should be
* triggered regardless if the container or list entry was changed once
* or multiple times.
*
* dnode
* libyang data node from the YANG list or container.
*/
void (*apply_finish)(const struct lyd_node *dnode);
Here’s an example of how this callback can be used:
/*
* XPath: /frr-ripd:ripd/instance/timers/
*/
static void ripd_instance_timers_apply_finish(const struct lyd_node *dnode)
{
/* Reset update timer thread. */
rip_event(RIP_UPDATE_EVENT, 0);
}
{
.xpath = "/frr-ripd:ripd/instance/timers",
.cbs.apply_finish = ripd_instance_timers_apply_finish,
.cbs.cli_show = cli_show_rip_timers,
},
{
.xpath = "/frr-ripd:ripd/instance/timers/flush-interval",
.cbs.modify = ripd_instance_timers_flush_interval_modify,
},
{
.xpath = "/frr-ripd:ripd/instance/timers/holddown-interval",
.cbs.modify = ripd_instance_timers_holddown_interval_modify,
},
{
.xpath = "/frr-ripd:ripd/instance/timers/update-interval",
.cbs.modify = ripd_instance_timers_update_interval_modify,
},
In this example, we want to call the rip_event() function only once
regardless if all RIP timers were modified or only one of them. Without
the apply_finish callback we’d need to call rip_event() in the
modify callback of each timer (a YANG leaf), resulting in redundant
call to the rip_event() function if multiple timers are changed at
once.
Bonus: libyang user types
When writing YANG modules, it’s advisable to create derived types for data types that are used on multiple places (e.g. MAC addresses, IS-IS networks, etc). Here’s how RFC 7950 defines derived types: > YANG can define derived types from base types using the “typedef” > statement. A base type can be either a built-in type or a derived > type, allowing a hierarchy of derived types. > > A derived type can be used as the argument for the “type” statement. > > YANG Example: > > typedef percent { > type uint8 { > range “0 .. 100”; > } > } > > leaf completed { > type percent; > }
Derived types are essentially built-in types with imposed restrictions.
As an example, the ipv4-address derived type from IETF is defined
using the string built-in type with a pattern constraint (a
regular expression):
typedef ipv4-address {
type string {
pattern
'(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}'
+ '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
+ '(%[\p{N}\p{L}]+)?';
}
description
"The ipv4-address type represents an IPv4 address in
dotted-quad notation. The IPv4 address may include a zone
index, separated by a % sign.
The zone index is used to disambiguate identical address
values. For link-local addresses, the zone index will
typically be the interface index number or the name of an
interface. If the zone index is not present, the default
zone of the device will be used.
The canonical format for the zone index is the numerical
format";
}
Sometimes, however, it’s desirable to have a binary representation of
the derived type that is different from the associated built-in type.
Taking the ipv4-address example above, it would be more convenient
to manipulate this YANG type using in_addr structures instead of
strings. libyang allow us to do that using the user types plugin:
https://netopeer.liberouter.org/doc/libyang/master/howtoschemaplugins.html#usertypes
Here’s how the the ipv4-address derived type is implemented in FRR
(yang/libyang_plugins/frr_user_types.c):
static int ipv4_address_store_clb(const char *type_name, const char *value_str,
lyd_val *value, char **err_msg)
{
value->ptr = malloc(sizeof(struct in_addr));
if (!value->ptr)
return 1;
if (inet_pton(AF_INET, value_str, value->ptr) != 1) {
free(value->ptr);
return 1;
}
return 0;
}
struct lytype_plugin_list frr_user_types[] = {
{"ietf-inet-types", "2013-07-15", "ipv4-address",
ipv4_address_store_clb, free},
{"ietf-inet-types", "2013-07-15", "ipv4-address-no-zone",
ipv4_address_store_clb, free},
[snip]
{NULL, NULL, NULL, NULL, NULL} /* terminating item */
};
Now, in addition to the string representation of the data value, libyang
will also store the data in the binary format we specified (an
in_addr structure).
Whenever a new derived type is implemented in FRR, it’s also recommended
to write new wrappers in the lib/yang_wrappers.c file
(e.g. yang_dnode_get_ipv4(), yang_get_default_ipv4(), etc).
Step 5: rewrite the CLI commands as dumb wrappers around the northbound callbacks
Once the northbound callbacks are implemented, we need to rewrite the associated CLI commands on top of the northbound layer. This is the easiest part of the retrofitting process.
For protocol daemons, it’s recommended to put all CLI commands on a separate C file (e.g. ripd/rip_cli.c). This helps to keep the code more clean by separating the main protocol code from the user interface. It should also help when moving the CLI to a separate program in the future.
For libfrr commands, it’s not possible to centralize all commands in a
single file because the extract.pl script from vtysh treats commands
differently depending on the file in which they are defined (e.g. DEFUNs
from lib/routemap.c are installed using the VTYSH_RMAP_SHOW constant,
which identifies the daemons that support route-maps). In this case, the
CLI commands should be rewritten but maintained in the same file.
Since all CLI configuration commands from FRR will need to be rewritten, this is an excellent opportunity to rework this part of the code to make the commands easier to maintain and extend. These are the three main recommendations:
Always use DEFPY instead of DEFUN to improve code readability
Always try to join multiple DEFUNs into a single DEFPY whenever possible. As an example, there’s no need to have both
distance (1-255) A.B.C.D/Manddistance (1-255) A.B.C.D/M WORDwhen a singledistance (1-255) A.B.C.D/M [WORD]would suffice.When making a negative form of a command, put
[no]in the positive form and use![...]to mark portions of the command that should be optional only in thenoversion.
To rewrite a CLI command as a dumb wrapper around the northbound
callbacks, use the nb_cli_cfg_change() function. This function
accepts as a parameter an array of cli_config_change structures that
specify the changes that need to performed on the candidate
configuration. Here’s the declaration of this structure (taken from the
lib/northbound_cli.h file):
struct cli_config_change {
/*
* XPath (absolute or relative) of the configuration option being
* edited.
*/
char xpath[XPATH_MAXLEN];
/*
* Operation to apply (either NB_OP_CREATE, NB_OP_MODIFY or
* NB_OP_DESTROY).
*/
enum nb_operation operation;
/*
* New value of the configuration option. Should be NULL for typeless
* YANG data (e.g. presence-containers). For convenience, NULL can also
* be used to restore a leaf to its default value.
*/
const char *value;
};
The nb_cli_cfg_change() function positions the CLI command on top on
top of the northbound layer. Instead of changing the running
configuration directly, this function changes the candidate
configuration instead, as described in the [[Transactional CLI]] page.
When the transactional CLI is not in use (i.e. the default mode), then
nb_cli_cfg_change() performs an implicit commit operation after
changing the candidate configuration.
NOTE: the
nb_cli_cfg_change()function clones the candidate configuration before actually editing it. This way, if any error happens during the editing, the original candidate is restored to avoid inconsistencies. Either all changes from the configuration command are performed successfully or none are. It’s like a mini-transaction but happening on the candidate configuration (thus the northbound callbacks are not involved).
Other important details to keep in mind while rewriting the CLI commands:
nb_cli_cfg_change()returns CLI errors codes (e.g.CMD_SUCCESS,CMD_WARNING), so the return value of this function can be used as the return value of CLI commands.Calls to
VTY_PUSH_CONTEXTandVTY_PUSH_CONTEXT_SUBshould be converted to calls toVTY_PUSH_XPATH. Similarly, the following macros aren’t necessary anymore and can be removed:VTY_DECLVAR_CONTEXTVTY_DECLVAR_CONTEXT_SUBVTY_GET_CONTEXTVTY_CHECK_CONTEXT.
The
nb_cli_cfg_change()functions uses theVTY_CHECK_XPATHmacro to check if the data node being edited still exists before doing anything else.
The examples below provide additional details about how the conversion should be done.
Example 1
In this first example, the router rip command becomes a dumb wrapper
around the ripd_instance_create() callback. Note that we don’t need
to check if the /frr-ripd:ripd/instance data path already exists
before trying to create it. The northbound will detect when this
presence-container already exists and do nothing. The
VTY_PUSH_XPATH() macro is used to change the vty node and set the
context for other commands under router rip.
DEFPY_NOSH (router_rip,
router_rip_cmd,
"router rip",
"Enable a routing process\n"
"Routing Information Protocol (RIP)\n")
{
int ret;
struct cli_config_change changes[] = {
{
.xpath = "/frr-ripd:ripd/instance",
.operation = NB_OP_CREATE,
.value = NULL,
},
};
ret = nb_cli_cfg_change(vty, NULL, changes, array_size(changes));
if (ret == CMD_SUCCESS)
VTY_PUSH_XPATH(RIP_NODE, changes[0].xpath);
return ret;
}
Example 2
Here we can see the use of relative xpaths (starting with ./), which
are more convenient that absolute xpaths (which would be
/frr-ripd:ripd/instance/default-metric in this example). This is
possible because the use of VTY_PUSH_XPATH() in the router rip
command set the vty base xpath to /frr-ripd:ripd/instance.
DEFPY (rip_default_metric,
rip_default_metric_cmd,
"default-metric (1-16)",
"Set a metric of redistribute routes\n"
"Default metric\n")
{
struct cli_config_change changes[] = {
{
.xpath = "./default-metric",
.operation = NB_OP_MODIFY,
.value = default_metric_str,
},
};
return nb_cli_cfg_change(vty, NULL, changes, array_size(changes));
}
In the command below we the value to NULL to indicate that we want
to set this leaf to its default value. This is better than hardcoding
the default value because the default might change in the future. Also,
users might define custom defaults by using YANG deviations, so it’s
better to write code that works correctly regardless of the default
values defined in the YANG models.
DEFPY (no_rip_default_metric,
no_rip_default_metric_cmd,
"no default-metric [(1-16)]",
NO_STR
"Set a metric of redistribute routes\n"
"Default metric\n")
{
struct cli_config_change changes[] = {
{
.xpath = "./default-metric",
.operation = NB_OP_MODIFY,
.value = NULL,
},
};
return nb_cli_cfg_change(vty, NULL, changes, array_size(changes));
}
Example 3
This example shows how one command can change multiple leaves at the same time.
DEFPY (rip_timers,
rip_timers_cmd,
"timers basic (5-2147483647)$update (5-2147483647)$timeout (5-2147483647)$garbage",
"Adjust routing timers\n"
"Basic routing protocol update timers\n"
"Routing table update timer value in second. Default is 30.\n"
"Routing information timeout timer. Default is 180.\n"
"Garbage collection timer. Default is 120.\n")
{
struct cli_config_change changes[] = {
{
.xpath = "./timers/update-interval",
.operation = NB_OP_MODIFY,
.value = update_str,
},
{
.xpath = "./timers/holddown-interval",
.operation = NB_OP_MODIFY,
.value = timeout_str,
},
{
.xpath = "./timers/flush-interval",
.operation = NB_OP_MODIFY,
.value = garbage_str,
},
};
return nb_cli_cfg_change(vty, NULL, changes, array_size(changes));
}
Example 4
This example shows how to create a list entry:
DEFPY (rip_distance_source,
rip_distance_source_cmd,
"distance (1-255) A.B.C.D/M$prefix [WORD$acl]",
"Administrative distance\n"
"Distance value\n"
"IP source prefix\n"
"Access list name\n")
{
char xpath_list[XPATH_MAXLEN];
struct cli_config_change changes[] = {
{
.xpath = ".",
.operation = NB_OP_CREATE,
},
{
.xpath = "./distance",
.operation = NB_OP_MODIFY,
.value = distance_str,
},
{
.xpath = "./access-list",
.operation = acl ? NB_OP_MODIFY : NB_OP_DESTROY,
.value = acl,
},
};
snprintf(xpath_list, sizeof(xpath_list), "./distance/source[prefix='%s']",
prefix_str);
return nb_cli_cfg_change(vty, xpath_list, changes, array_size(changes));
}
The xpath_list variable is used to hold the xpath that identifies
the list entry. The keys of the list entry should be embedded in this
xpath and don’t need to be part of the array of configuration changes.
All entries from the changes array use relative xpaths which are
based on the xpath of the list entry.
The access-list optional leaf can be either modified or deleted
depending whether the optional WORD parameter is present or not.
When deleting a list entry, all non-key leaves can be ignored:
DEFPY (no_rip_distance_source,
no_rip_distance_source_cmd,
"no distance (1-255) A.B.C.D/M$prefix [WORD$acl]",
NO_STR
"Administrative distance\n"
"Distance value\n"
"IP source prefix\n"
"Access list name\n")
{
char xpath_list[XPATH_MAXLEN];
struct cli_config_change changes[] = {
{
.xpath = ".",
.operation = NB_OP_DESTROY,
},
};
snprintf(xpath_list, sizeof(xpath_list), "./distance/source[prefix='%s']",
prefix_str);
return nb_cli_cfg_change(vty, xpath_list, changes, 1);
}
Example 5
This example shows a DEFPY statement that performs two validations
before calling nb_cli_cfg_change():
DEFPY (ip_rip_authentication_string,
ip_rip_authentication_string_cmd,
"ip rip authentication string LINE$password",
IP_STR
"Routing Information Protocol\n"
"Authentication control\n"
"Authentication string\n"
"Authentication string\n")
{
struct cli_config_change changes[] = {
{
.xpath = "./frr-ripd:rip/authentication/password",
.operation = NB_OP_MODIFY,
.value = password,
},
};
if (strlen(password) > 16) {
vty_out(vty,
"%% RIPv2 authentication string must be shorter than 16\n");
return CMD_WARNING_CONFIG_FAILED;
}
if (yang_dnode_exists(vty->candidate_config->dnode, "%s%s",
VTY_GET_XPATH,
"/frr-ripd:rip/authentication/key-chain")) {
vty_out(vty, "%% key-chain configuration exists\n");
return CMD_WARNING_CONFIG_FAILED;
}
return nb_cli_cfg_change(vty, NULL, changes, array_size(changes));
}
These two validations are not strictly necessary since the configuration change is validated using libyang afterwards. The issue with the libyang validation is that the error messages from libyang are too verbose:
ripd# conf t
ripd(config)# interface eth0
ripd(config-if)# ip rip authentication string XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
% Failed to edit candidate configuration.
Value "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" does not satisfy the constraint "1..16" (range, length, or pattern).
Failed to create node "authentication-password" as a child of "rip".
YANG path: /frr-interface:lib/interface[name='eth0'][vrf='Default-IP-Routing-Table']/frr-ripd:rip/authentication-password
On the other hand, the original error message from ripd is much cleaner:
ripd# conf t
ripd(config)# interface eth0
ripd(config-if)# ip rip authentication string XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
% RIPv2 authentication string must be shorter than 16
The second validation is a bit more complex. If we try to create the
authentication/password leaf when the authentication/key-chain
leaf already exists (both are under a YANG choice statement), libyang
will automatically delete the authentication/key-chain and create
authentication/password on its place. This is different from the
original ripd behavior where the ip rip authentication key-chain
command must be removed before configuring the ip rip authentication
string command.
In the spirit of not introducing any backward-incompatible changes in the CLI, converted commands should retain some of their validation checks to preserve their original behavior.
Step 6: implement the cli_show callbacks
The traditional method used by FRR to display the running configuration
consists of looping through all CLI nodes all call their func
callbacks one by one, which in turn read the configuration from internal
variables and dump them to the terminal in the form of CLI commands.
The problem with this approach is twofold. First, since the callbacks read the configuration from internal variables, they can’t display anything other than the running configuration. Second, they don’t have the ability to display default values when requested by the user (e.g. show configuration candidate with-defaults).
The new northbound architecture solves these problems by introducing a
new callback: cli_show. Here’s the signature of this function (taken
from the lib/northbound.h file):
/*
* Optional callback to show the CLI command associated to the given
* YANG data node.
*
* vty
* the vty terminal to dump the configuration to
*
* dnode
* libyang data node that should be shown in the form of a CLI
* command
*
* show_defaults
* specify whether to display default configuration values or not.
* This parameter can be ignored most of the time since the
* northbound doesn't call this callback for default leaves or
* non-presence containers that contain only default child nodes.
* The exception are commands associated to multiple configuration
* options, in which case it might be desirable to hide one or more
* parts of the command when this parameter is set to false.
*/
void (*cli_show)(struct vty *vty, struct lyd_node *dnode,
bool show_defaults);
One of the main differences to the old CLI func callbacks is that
the cli_show callbacks are associated to YANG data paths and not to
CLI nodes. This means we can define one separate callback for each CLI
command, making the code more modular and easier to maintain (among
other advantages that will be more clear later). For enhanced code
readability, it’s recommended to position the cli_show callbacks
immediately after their associated command definitions (DEFPYs).
The cli_show callbacks are used by the nb_cli_show_config_cmds()
function to display configurations stored inside nb_config
structures. The configuration being displayed can be anything from the
running configuration (show configuration running), a candidate
configuration (show configuration candidate) or a rollback
configuration (show configuration transaction (1-4294967296)). The
nb_cli_show_config_cmds() function works by iterating over all data
nodes from the given configuration and calling the cli_show callback
for the nodes where it’s defined. If a list has dozens of entries, the
cli_show callback associated to this list will be called multiple
times with the dnode parameter pointing to different list entries on
each iteration.
For backward compatibility with the show running-config command, we
can’t get rid of the CLI func callbacks at this point in time.
However, we can make the CLI func callbacks call the corresponding
cli_show callbacks to avoid code duplication. The
nb_cli_show_dnode_cmds() function can be used for that purpose. Once
the CLI retrofitting process finishes for all FRR daemons, we can remove
the legacy CLI func callbacks and turn show running-config into a
shorthand for show configuration running.
Regarding displaying configuration with default values, this is
something that is taken care of by the nb_cli_show_config_cmds()
function itself. When the show configuration command is used without
the with-defaults option, nb_cli_show_config_cmds() will skip
calling cli_show callbacks for data nodes that contain only default
values (e.g. default leaves or non-presence containers that contain only
default child nodes). There are however some exceptional cases where the
implementer of the cli_show callback should take into consideration
if default values should be displayed or not. This and other concepts
will be explained in more detail in the examples below.
Example 1
Command: default-metric (1-16)
YANG representation:
leaf default-metric {
type uint8 {
range "1..16";
}
default "1";
description
"Default metric of redistributed routes.";
}
Placement of the cli_show callback:
{
.xpath = "/frr-ripd:ripd/instance/default-metric",
.cbs.modify = ripd_instance_default_metric_modify,
+ .cbs.cli_show = cli_show_rip_default_metric,
},
Implementation of the cli_show callback:
void cli_show_rip_default_metric(struct vty *vty, struct lyd_node *dnode,
bool show_defaults)
{
vty_out(vty, " default-metric %s\n",
yang_dnode_get_string(dnode, NULL));
}
In this first example, the default-metric command was modeled using a
YANG leaf, and we added a new cli_show callback attached to the YANG
path of this leaf.
The callback makes use of the yang_dnode_get_string() function to
obtain the string value of the configuration option. The following would
also be possible:
vty_out(vty, " default-metric %u\n",
yang_dnode_get_uint8(dnode, NULL));
Both options are possible because libyang stores both a binary
representation and a textual representation of all values stored in a
data node (lyd_node). For simplicity, it’s recommended to always use
yang_dnode_get_string() in the cli_show callbacks.
Example 2
Command: router rip
YANG representation:
container instance {
presence "Present if the RIP protocol is enabled.";
description
"RIP routing instance.";
[snip]
}
Placement of the cli_show callback:
{
.xpath = "/frr-ripd:ripd/instance",
.cbs.create = ripd_instance_create,
.cbs.delete = ripd_instance_delete,
+ .cbs.cli_show = cli_show_router_rip,
},
Implementation of the cli_show callback:
void cli_show_router_rip(struct vty *vty, struct lyd_node *dnode,
bool show_defaults)
{
vty_out(vty, "!\n");
vty_out(vty, "router rip\n");
}
In this example, the cli_show callback doesn’t need to obtain any
value from the dnode parameter since presence-containers don’t hold
any data (apart from their child nodes, but they have their own
cli_show callbacks).
Example 3
Command: timers basic (5-2147483647) (5-2147483647) (5-2147483647)
YANG representation:
container timers {
description
"Settings of basic timers";
leaf flush-interval {
type uint32 {
range "5..2147483647";
}
units "seconds";
default "120";
description
"Interval before a route is flushed from the routing
table.";
}
leaf holddown-interval {
type uint32 {
range "5..2147483647";
}
units "seconds";
default "180";
description
"Interval before better routes are released.";
}
leaf update-interval {
type uint32 {
range "5..2147483647";
}
units "seconds";
default "30";
description
"Interval at which RIP updates are sent.";
}
}
Placement of the cli_show callback:
{
+ .xpath = "/frr-ripd:ripd/instance/timers",
+ .cbs.cli_show = cli_show_rip_timers,
+ },
+ {
.xpath = "/frr-ripd:ripd/instance/timers/flush-interval",
.cbs.modify = ripd_instance_timers_flush_interval_modify,
},
{
.xpath = "/frr-ripd:ripd/instance/timers/holddown-interval",
.cbs.modify = ripd_instance_timers_holddown_interval_modify,
},
{
.xpath = "/frr-ripd:ripd/instance/timers/update-interval",
.cbs.modify = ripd_instance_timers_update_interval_modify,
},
Implementation of the cli_show callback:
void cli_show_rip_timers(struct vty *vty, struct lyd_node *dnode,
bool show_defaults)
{
vty_out(vty, " timers basic %s %s %s\n",
yang_dnode_get_string(dnode, "./update-interval"),
yang_dnode_get_string(dnode, "./holddown-interval"),
yang_dnode_get_string(dnode, "./flush-interval"));
}
This command is a bit different since it changes three leaves at the
same time. This means we need to have a single cli_show callback in
order to display the three leaves together in the same line.
The new cli_show_rip_timers() callback was added attached to the
timers non-presence container that groups the three leaves. Without
the timers non-presence container we’d need to display the timers
basic command inside the cli_show_router_rip() callback, which
would break our requirement of having a separate cli_show callback
for each configuration command.
Example 4
Command:
redistribute <kernel|connected|static|ospf|isis|bgp|eigrp|nhrp|table|vnc|babel|sharp> [{metric (0-16)|route-map WORD}]
YANG representation:
list redistribute {
key "protocol";
description
"Redistributes routes learned from other routing protocols.";
leaf protocol {
type frr-route-types:frr-route-types-v4;
description
"Routing protocol.";
must '. != "rip"';
}
leaf route-map {
type string {
length "1..max";
}
description
"Applies the conditions of the specified route-map to
routes that are redistributed into the RIP routing
instance.";
}
leaf metric {
type uint8 {
range "0..16";
}
description
"Metric used for the redistributed route. If a metric is
not specified, the metric configured with the
default-metric attribute in RIP router configuration is
used. If the default-metric attribute has not been
configured, the default metric for redistributed routes
is 0.";
}
}
Placement of the cli_show callback:
{
.xpath = "/frr-ripd:ripd/instance/redistribute",
.cbs.create = ripd_instance_redistribute_create,
.cbs.delete = ripd_instance_redistribute_delete,
+ .cbs.cli_show = cli_show_rip_redistribute,
},
{
.xpath = "/frr-ripd:ripd/instance/redistribute/route-map",
.cbs.modify = ripd_instance_redistribute_route_map_modify,
.cbs.delete = ripd_instance_redistribute_route_map_delete,
},
{
.xpath = "/frr-ripd:ripd/instance/redistribute/metric",
.cbs.modify = ripd_instance_redistribute_metric_modify,
.cbs.delete = ripd_instance_redistribute_metric_delete,
},
Implementation of the cli_show callback:
void cli_show_rip_redistribute(struct vty *vty, struct lyd_node *dnode,
bool show_defaults)
{
vty_out(vty, " redistribute %s",
yang_dnode_get_string(dnode, "./protocol"));
if (yang_dnode_exists(dnode, "./metric"))
vty_out(vty, " metric %s",
yang_dnode_get_string(dnode, "./metric"));
if (yang_dnode_exists(dnode, "./route-map"))
vty_out(vty, " route-map %s",
yang_dnode_get_string(dnode, "./route-map"));
vty_out(vty, "\n");
}
Similar to the previous example, the redistribute command changes
several leaves at the same time, and we need a single callback to
display all leaves in a single line in accordance to the CLI command. In
this case, the leaves are already grouped by a YANG list so there’s no
need to add a non-presence container. The new cli_show callback was
attached to the YANG path of the list.
It’s also worth noting the use of the yang_dnode_exists() function
to check if optional leaves exist in the configuration before displaying
them.
Example 5
Command:
ip rip authentication mode <md5 [auth-length <rfc|old-ripd>]|text>
YANG representation:
container authentication-scheme {
description
"Specify the authentication scheme for the RIP interface";
leaf mode {
type enumeration {
[snip]
}
default "none";
description
"Specify the authentication mode.";
}
leaf md5-auth-length {
when "../mode = 'md5'";
type enumeration {
[snip]
}
default "20";
description
"MD5 authentication data length.";
}
}
Placement of the cli_show callback:
+ {
+ .xpath = "/frr-interface:lib/interface/frr-ripd:rip/authentication-scheme",
+ .cbs.cli_show = cli_show_ip_rip_authentication_scheme,
},
{
.xpath = "/frr-interface:lib/interface/frr-ripd:rip/authentication-scheme/mode",
.cbs.modify = lib_interface_rip_authentication_scheme_mode_modify,
},
{
.xpath = "/frr-interface:lib/interface/frr-ripd:rip/authentication-scheme/md5-auth-length",
.cbs.modify = lib_interface_rip_authentication_scheme_md5_auth_length_modify,
.cbs.delete = lib_interface_rip_authentication_scheme_md5_auth_length_delete,
},
Implementation of the cli_show callback:
void cli_show_ip_rip_authentication_scheme(struct vty *vty,
struct lyd_node *dnode,
bool show_defaults)
{
switch (yang_dnode_get_enum(dnode, "./mode")) {
case RIP_NO_AUTH:
vty_out(vty, " no ip rip authentication mode\n");
break;
case RIP_AUTH_SIMPLE_PASSWORD:
vty_out(vty, " ip rip authentication mode text\n");
break;
case RIP_AUTH_MD5:
vty_out(vty, " ip rip authentication mode md5");
if (show_defaults
|| !yang_dnode_is_default(dnode, "./md5-auth-length")) {
if (yang_dnode_get_enum(dnode, "./md5-auth-length")
== RIP_AUTH_MD5_SIZE)
vty_out(vty, " auth-length rfc");
else
vty_out(vty, " auth-length old-ripd");
}
vty_out(vty, "\n");
break;
}
}
This is the most complex cli_show callback we have in ripd. Its
complexity comes from the following:
The
ip rip authentication mode ...command changes two YANG leaves at the same time.Part of the command should be hidden when the
show_defaultsparameter is set to false.
This is the behavior we want to implement:
ripd(config)# interface eth0
ripd(config-if)# ip rip authentication mode md5
ripd(config-if)#
ripd(config-if)# show configuration candidate
Configuration:
!
[snip]
!
interface eth0
ip rip authentication mode md5
!
end
ripd(config-if)#
ripd(config-if)# show configuration candidate with-defaults
Configuration:
!
[snip]
!
interface eth0
[snip]
ip rip authentication mode md5 auth-length old-ripd
!
end
Note that auth-length old-ripd should be hidden unless the
configuration is shown using the with-defaults option. This is why the
cli_show_ip_rip_authentication_scheme() callback needs to consult
the value of the show_defaults parameter. It’s expected that only a
very small minority of all cli_show callbacks will need to consult
the show_defaults parameter (there’s a chance this might be the only
case!)
In the case of the timers basic command seen before, we need to
display the value of all leaves even if only one of them has a value
different from the default. Hence the cli_show_rip_timers() callback
was able to completely ignore the show_defaults parameter.
Step 7: consolidation
As mentioned in the fourth step, the northbound retrofitting process can happen gradually over time, since both “old” and “new” commands can coexist without problems. Once all commands from a given daemon were converted, we can proceed to the consolidation step, which consists of the following:
Remove the vty configuration lock, which is enabled by default in all daemons. Now multiple users should be able to edit the configuration concurrently, using either shared or private candidate configurations.
Reference commit: 57dccdb1.
Stop using the qobj infrastructure to keep track of configuration objects. This is not necessary anymore, the northbound uses a similar mechanism to keep track of YANG data nodes in the candidate configuration.
Reference commit: 4e6d63ce.
Make the daemon SIGHUP handler re-read the configuration file (and ensure it’s not doing anything other than that).
Reference commit: 5e57edb4.
Final Considerations
Testing
Converting CLI commands to the new northbound model can be a complicated task for beginners, but the more commands one converts, the easier it gets. It’s highly recommended to perform as much testing as possible on the converted commands to reduce the likelihood of introducing regressions. Tools like topotests, ANVL and the CLI fuzzer can be used to catch hidden bugs that might be present. As usual, it’s also recommended to use valgrind and static code analyzers to catch other types of problems like memory leaks.
Amount of work
The output below gives a rough estimate of the total number of configuration commands that need to be converted per daemon:
$ for dir in lib zebra bgpd ospfd ospf6d isisd ripd ripngd eigrpd pimd pbrd ldpd nhrpd babeld ; do echo -n "$dir: " && cd $dir && grep -ERn "DEFUN|DEFPY" * | grep -Ev "clippy|show|clear" | wc -l && cd ..; done
lib: 302
zebra: 181
bgpd: 569
ospfd: 198
ospf6d: 99
isisd: 126
ripd: 64
ripngd: 44
eigrpd: 58
pimd: 113
pbrd: 9
ldpd: 46
nhrpd: 24
babeld: 28
As it can be seen, the northbound retrofitting process will demand a lot of work from FRR developers and should take months to complete. Everyone is welcome to collaborate!