Tail-f's ConfD is a device configuration toolkit meant to be integrated as a management sub-system
in network devices, providing:
• An implementation of the NETCONF protocol
• Automatic rendering of northbound interfaces, including CLI, Web UI and NETCONF
• Clustered/fault-tolerant storage of configuration data
• Master-agent/sub-agent framework for NETCONF, CLI, Web UI and SNMP
ConfD executes as a regular Unix daemon on the target device, acting:
• as a NETCONF agent for the NETCONF protocol
• as a Web server for the Web UI
• as a CLI engine for command-line access
• and as an SNMP agent
It also contains a built-in XML configuration database.
The following figure illustrates the overall architecture. The ConfD architecture is modular, with welldefined
interfaces between sub-systems
The NETCONF, SNMP, CLI and Web modules are Management Agents. These communicate with
external managers, and provide the managers with a protocol-specific view of the system. The box
labeled Other Agent is e.g. a GUI application or some other management protocol implementation.
These other Agents use the Management Agent API (MAAPI) to talk to the Management Backplane.
The Management Backplane provides an hierarchical view of the configuration and status/statistics
data through the Management Agent API. This API is a session-oriented read/write API to the
hierarchical data, with transaction-like semantics.
Examples of operations in this interface are 'create-subtree', 'get-instance', 'set-instance'. This interface
is used both when the configuration is stored in the built-in ConfD database, and when it is stored in
an external database.
The Management Backplane authenticates incoming requests through an AAA (Authentication,
Authorization, Accounting) plugin API. An AAA plugin authenticates users and authorizes their
requests. ConfD comes with a built-in AAA plugin, which can be replaced by vendor specific code.
In order to actually read and write the device-native configuration data, the sessions in the Management
Backplane use the Database Plugin API. A database plugin has to provide mapping from the
hierarchical view of the data used in the management protocols, to the native view used by the
management database.
The management database can either be the integrated management database - called CDB - or some
other database. CDB is a light-weight fault-tolerant distributed XML database. CDB can be used in
single or multi-node systems in master slave configuration. It handles updates to the database schema
automatically.
The YANG Data Modeling Language
YANG is a data modeling language used to model configuration and state data manipulated by a
NETCONF agent.
YANG is the chosen language to create data models for the the NETCONF protocol (RFC 4741)
which currently does not provide a standardized way to describe data models. Instead, vendors are
forced to use proprietary solutions. In order for NETCONF to be an interoperable protocol, models
must be defined in a vendor-neutral way. YANG provides the language and rules for defining such
models for use with NETCONF.
Using NETCONF
NETCONF is a powerful protocol that can be used to programmatically reconfigure a device. We're
still running ConfD with the links.yang data model.
The easiest way to interact with the NETCONF agent in ConfD is to use a small python based program
called netconf-console that ships with ConfD. Let's just run it from the UNIX prompt and see what
we get:
ConfD 's built-in authentication and authorization mechanisms.
Users log into ConfD through the CLI, NETCONF, SNMP, or via the Web UI. In either case, users
need to be authenticated. That is, a user needs to present credentials, such as a password or a public
key in order to gain access.
Once a user is authenticated, all operations performed by that user need to be authorized. That
is, certain users may be allowed to perform certain tasks, whereas others are not. This is called
authorization. We differentiate between authorization of commands and authorization of data access.The AAA information describes which users may login, what passwords they have and what they are allowed to do.
ConfD itself is configured through a configuration file - confd.conf.Depending on northbound management protocol, when a user session is created in ConfD, it may or may not be authenticated.
Public Key Login
When a user logs over NETCONF or the CLI using the built-in SSH server, with public key login,
the procedure is as follows.
The user presents a username in accordance with the SSH protocol.
1. If the SSH keys in /aaa/authentication/users/user{$USER}/ssh_keydir match
the keys presented by the user, authentication succeeds.
2. Otherwise, if the user /aaa/authentication/users/user{$USER} does not exist, but
the user exists in /etc/passwd, the keys in the user's $HOME/.ssh directory are checked. If
these keys match the SSH keys presented by the user, authentication succeeds.
3. Otherwise, authentication fails.
If authentication succeeds, the user's group membership is established.
“Group Membership”.
This is exactly the same procedure that is used by the OpenSSH server with the exception that the built
in SSH server also locates the directory containing the public keys for a specific user by consulting
the /aaa/authentication/users tree.
We need to provide a directory where SSH keys are kept for a specific user. If public key login is not
desired at all for a user, the value of the ssh_keydir element should be set to "", i.e. the empty
string. Similarly, if the directory does not contain any SSH keys, public key logins for that user will
be disabled.
Password Login
Password login is triggered in the following cases:
• When a user logs in over NETCONF or the CLI using the built in SSH server, with a password.
The user presents a username and a password in accordance with the SSH protocol.
• When a user logs in using the Web UI. The Web UI asks for a username and password.
• When the function maapi_authenticate() is used.
In this case, ConfD will by default try local authentication, PAM, and external authentication, in that
order, as described below. It is possible to change the order in which these are tried, by modifying the
confd.conf . parameter /confdConfig/aaa/authOrder . See confd.conf(5) for details.
1. If /aaa/authentication/users/user{$USER} exists and the presented password
matches the encrypted password in /aaa/authentication/users/user{$USER}/
password the user is authenticated.
2. If the password does not match or if the user does not exist in /aaa/authentication/users,
PAM login is attempted, if enabled. See Section 14.4.3, “PAM” for details.
3. If all of the above fails and external authentication is enabled, the configured executable is invoked.
See Section 14.4.4, “External authentication” for details.
If authentication succeeds, the user's group membership is established.
“Group Membership”.
Group Membership
Once a user is authenticated, group membership must be established. All groups are stored under /
aaa/authentication/groups and each group contains a number of usernames.
A single user can be a member of several groups. Group membership is used by the authorization rules
to decide which operations a certain user is allowed to perform. Thus the ConfD AAA authorization
model is entirely group based. This is also sometimes referred to as role based authorization.
A valid group entry could thus look like:
The above XML data would then mean that users bob and joe are members of the admin group. The
users need not necessarily exist as actual users under /aaa/authentication/users in order
to belong to a group. If for example PAM authentication is used, it does not make sense to have all
users listed under /aaa/authentication/users.
The user is assigned to groups by consulting data under /aaa/authentication/groups, by
consulting the /etc/group file, and by any additional groups supplied by the authentication method.
The resulting group assignment is the union of these three methods, if it is non-empty. Otherwise, the
default group is used, if configured (/confdConfig/aaa/defaultGroup in confd.conf
A user entry has a UNIX uid and UNIX gid assigned to it. Groups may have optional group ids. When
a user is logged in, and ConfD tries to execute commands on behalf of that user, the uid/gid for the
command execution is taken from the user entry. Furthermore, UNIX supplementary group ids are
assigned according to the gids in the groups where the user is a member.
Authorization
Once a user is authenticated and group membership is established, when the user starts to perform
various actions, each action must be authorized. Normally the authorization is done based on
rules configured in the AAA data model as described in this section, but if needed we can also
register application callbacks to partially or completely replace this logic, see the section called
“AUTHORIZATION CALLBACKS” in confd_lib(3).
We differentiate between command authorization and data authorization.
Command authorization
The command authorization rules is an ordered list of rules
Each rule has six fields. The first is the index, the following four fields are matching fields. When
ConfD tries to run a command it tries to match the command towards the four matching rules and if all
four fields context, command, group, and op match, the sixth field, i.e. the action, is applied.
index index is the number of the rule. The rules are checked in order.
context context is either of the strings cli, netconf, webui, or * for a command rule.
This means that we can differentiate authorization rules for which access is used. Thus if
command access is attempted through the CLI the context will be the string cli whereas
if a user attempts to invoke a command over the NETCONF agent, the context will be
the string netconf
command This is the actual command getting executed. If the rule applies to NETCONF, the string
value of the rule is the name of any of the NETCONF commands such as edit-config.
If the rule applies to one or several CLI commands, the string is a space separated list
of CLI command tokens, for example request system reboot. If the command
applies to Web UI commands, it is a space separated string similar to a CLI string.
It's important to understand that a command rule for the CLI applies to the string as
entered by the user. The command rules are not aware of the data model. Thus it's not
possible to have a rule like:
group group is the name of the group for which the rule applies. The special string value *
matches all groups.
ops ops is the operation that ConfD tries to run. It must be a string of length less than or
equal to two, consisting only of characters taken from "rx". The different characters stand
for "read" and "execute".
action If all of the previous fields match, the rule as a whole matches and the value of action
will be taken. I.e. if a match is found, a decision is made whether to accept or reject the
request in its entirety.
1. If action is accept, the access attempt is accepted.
2. If action is accept_log, the access attempt is accepted and an entry is written into
the developer log. This is very useful when debugging command rules.
3. If action is reject, the access attempt is rejected and an entry is written into
the developer log. For the rule processing to be written to the devel log, the /
confdConfig/logs/developerLogLevel entry in confd.conf must be
set to trace.
Data authorization
A data authorization rule is defined as:
Similar to the command access check, whenever
item, access is checked. For a rule to match, five fields must match and when a match is found, the
corresponding action is chosen.
We have the following fields in the datarule list entry.
index index is the number of the rule. The rules are checked in order.
namespace The namespace string is the name of the namespace the rule applies to, (i.e. a URI).
The special value * matches everything.
It is also possible to have a trailing * on the URI string. This wild card feature
can be used if we choose to do revision by appending the revision number to the
URIs defining the namespaces. Doing revision management this way is bad, see
Section 3.13, “Module Names, Namespaces and Revisions”. It is recommended to to
revision management through the revision statement in YANG instead.
If for some reason, we do have revisions embedded in the URI defining the namespace
for some module anyway, regardless of it being a bad idea, we can utilize the * trick in
the AAA rules. Say that revision one has URI http://example.com/ns/ns/blaster/1.0 A
new software release has an updated model with a new version in the target namespace
called http://example.com/ns/blaster/1.1.
In order for the access rule to match regardless of the version of the target namespace
the context should be set to http://example.com/ns/blaster/*.
keypath keypath is a restricted XPath expression leading down into the populated XML tree.
A rule with a keypath matches if it is equal to or shorter than the checked path. Several
types of paths are allowed.
1. Tagpaths that are not containing any keys. For example /interfaces/
interface/mtu .
2. Instantiated key: as in /interfaces/interface[name="eth0"]/mask
matches the mask element only for the interface name "eth0". It's possible to
have partially instantiated paths only containing some keys instantiated - i.e
combinations of tagpaths and keypaths. Assuming a deeper tree, the path /hosts/
host[name="venus"]/servers/server/ip matches the "ip" element
for all servers, but only for the host named "venus".
3. Wild card at end as in: /interfaces/interface/* does not match /
interfaces/interface but rather all children of that path.
Thus the keypath in a rule is matched against the path in the attempted data access
command. If the attempted command has a path that is equal to or longer than the rule
path - we have a match.
context context is either of the strings cli, netconf, webui, snmp, or * for a data rule.
Furthermore, when we initiate user sessions from MAAPI, we can choose any string
we want.
Similarly to command rules we can differentiate access depending on which agent is
used to gain access.
group group is the name of the group for which the rule applies. The special value * applies
to all groups.
ops ops is the operation that ConfD tries to run. It must be either of
• A string of length less than or equal to three, consisting only of characters taken
from "rwx", in that order.
• A string of length less than or equal to five, consisting only of characters taken from
"crudx", in that order.
The different characters stand for "read", "write", "execute", "create", "update", and
"delete", where "write" is shorthand for the combination of "create", "update", and
"delete".
action This field has the same characteristics as the action field for command access.
The fields context, keypath, namespace, and group can either have an exact value, or the
special value *, which is a wildcard and matches everything.
When ConfD executes a command, the command rules in the authorization database are searched.
Rules are tried in order, ranging from low numbers towards higher. When a rule matches the operation
(command) that ConfD is attempting, the action of the matching rule is applied - whether accept or
reject.
When actual data access is attempted, the data rules are searched. E.g. when a user attempts to execute
delete aaa in the CLI, the user needs delete access to the entire tree /aaa.
Another example is if a CLI user writes show configuration aaa TAB it suffices to have
read access to at least one item below /aaa for the CLI to perform the TAB completion. If no rule
matches or an explicit reject rule is found, the CLI will not TAB complete.
Yet another example is if a user tries to execute delete aaa authentication users, we
need to perform a check on the paths /aaa and /aaa/authentication before attempting to
delete the sub tree. Say that we have rule number 100 for path /aaa/authentication/users
which is an accept rule and we have rule 101 for path /aaa which is a reject rule. With this rule set
the user should indeed be allowed to delete the entire /aaa/authentication/users tree but
not the /aaa tree nor the /aaa/authentication tree.
We have two variations on how the rules are processed. The easy case is when we actually try to read
or write an item in the configuration database. The execution goes like:
The idea being that as we traverse (through TAB) down the XML tree, as long as there is at least one
rule that can possibly match later, once we have more data, we must continue.
For example assume we have:
1. "/system/config/foo" --> accept
2. "/system/config" --> reject
If we in the CLI stand at "/system/config" and hit TAB we want the CLI to show foo as a
completion, but none of the other elements that reside under /system/config. Whereas if we try
to execute delete /system/config the request must be rejected.
The execute permission on data access checks is used when we have modeled actions into our YANG
model. In order to execute an action we need to have execute access to the path in the XML tree where
the modeled action resides.
The keypath element can be used to specify explicit paths into the XML tree using XPath syntax.
For example the following rule:
Explicitly allows the admin group to change the password for precisely the bob user when the user is
using the CLI. Had keypath been /aaa/authentication/users/password the rule would
apply to all password elements for all users.
ConfD applies string substitution, whereby the username of the logged in user can be used in a
keypath. Thus:
The keypath element can be used to specify explicit paths into the XML tree using XPath syntax.
For example the following rule:
Explicitly allows the admin group to change the password for precisely the bob user when the user is
using the CLI. Had keypath been /aaa/authentication/users/password the rule would
apply to all password elements for all users.
ConfD applies string substitution, whereby the username of the logged in user can be used in a
keypath.
Two CLI modes
The ConfD CLI provides various commands for configuring and monitoring software, hardware,
and network connectivity of target devices. The CLI supports two modes: operational mode, for
monitoring the state of the device; and configure mode, for changing the state of the device.
The prompt indicates which mode the CLI is in. When moving from operational mode to configure
mode using the configure command, the prompt is changed from user@host> to user@host%.
The prompts can be configured using the prompt1 and prompt2 settings in the confd.conf file.
Operational mode
Operational mode is the initial mode after successful login to the CLI. It is primarily used for
viewing the system status, controlling the CLI environment, monitoring and troubleshooting network
connectivity, and initiating the configure mode.
The full list of commands available in operational mode is listed below in the "Operational mode
commands" section.
Configure mode
Configure mode can be initiated by entering the configure command in operational mode. All changes
to the device's configuration are done to a copy of the active configuration, called a candidate
configuration. These changes do not take effect until a successful commit or commit confirm
command is entered.
The full list of commands available in configure mode is listed below in the "Configure mode
commands" section.
Introduction to the ConfD SNMP Agent
The ConfD integrated SNMP agent provides an environment where SNMP and other agents such as
NETCONF, Web UI, and CLI, coexist and use the same built-in database (CDB) for configuration
storage and the same set of instrumentation functions for controlling managed objects (MOs). Simple
bindings from SNMP MIB objects to YANG objects is all that is needed to open up a configuration
database to be accessed by an SNMP manager.
The advantage of having an integrated SNMP agent in ConfD is that configuration data can be accessed
directly from the built-in database (CDB) or from user written managed objects without having to
do the tedious work of writing a separate set of instrumentation functions just for SNMP. One set
of common instrumentation functions is used for serving the NETCONF, CLI, Web UI, and SNMP
agents.
confdc --mib2yang is used to make YANG models from MIBs. It also provides the necessary bindings
from MIB objects to elements in the YANG model.
To go the opposite way, from YANG to MIBs, see Section 17.3, “Generating MIBs from YANG”.
The ConfD SNMP agent application provides the following features:
• An extensible SNMP agent which understands SNMPv1, SNMPv2c and SNMPv3.
• A MIB compiler which understands SMIv1 and SMIv2.
• Configuration data is specified in YANG models.
• Common instrumentation functions for controlling managed objects (MO's) via NETCONF, CLI,
Web UI, and SNMP agent.
• The SNMP agent uses ConfD AAA rules to determine access to data, as well as using the standard
SNMP view based and user based access control mechanisms.
• The following MIBs are supported by the ConfD SNMP agent:
• SNMPv2-MIB RFC 3418
• SNMP-FRAMEWORK-MIB RFC 3411
• SNMP-USER-BASED-SM-MIB RFC 3414
• SNMP-VIEW-BASED-ACM-MIB RFC 3415
• SNMP-COMMUNITY-MIB RFC 3584
• SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB RFC 3413
• SNMP-MPD-MIB RFC 3412
• TRANSPORT-ADDRESS-MIB RFC 3419
• SNMP-USM-AES-MIB RFC 3826
• IPV6-TC RFC 2465
Built-in MIB data
There is a set of standard MIBs which are used to control and configure an SNMP agent. These MIBs
are implemented in this agent. The user can control which of these MIBs are actually loaded into the
agent, and thus made visible to SNMP managers. For example, in a non-secure environment, it might
be a good idea to not make MIBs that define access control visible. Note, the data that the MIBs define
is used internally in the agent, even if the MIBs are not loaded.
Any SNMP agent must implement the system group and the snmp group, defined in SNMPv2-MIB.
This MIB will be loaded by default.
An SNMPv3 agent must implement the SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB. These
MIBs are also loaded by default, if the agent is configured for SNMPv3.
There are five other standard MIBs, which also may be loaded into the agent. These MIBs are:
• SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB which defines managed objects for
configuration of management targets, i.e. receivers of notifications (traps and informs). These MIBs
can be used with any SNMP version.
• SNMP-VIEW-BASED-ACM-MIB, which defines managed objects for access control. This MIB
can be used with any SNMP version.
• SNMP-COMMUNITY-MIB, which defines managed objects for coexistence of SNMPv1 and
SNMPv2c with SNMPv3. This MIB is only useful if SNMPv1 or SNMPv2c is used, possibly in
combination with SNMPv3.
• SNMP-USER-BASED-SM-MIB, which defines managed objects for authentication and privacy.
This MIB is only useful with SNMPv3.
USM and VACM and ConfD AAA
When the SNMP agent receives a SNMP request, it determines the securityName and SNMP context
for the request. If SNMPv1 or SNMPv2c is used, the snmpCommunityTable is consulted to determine
the securityName and SNMP context. If SNMPv3 is used, the SNMP context is explicitly given in the
request, and the securityName is determined from the usmUserTable.
If the context is not the default context (""), the request is rejected.
When the SNMP agent starts a user session in ConfD , it uses the securityName as the username, the
string "snmp" as ConfD AAA context, and no groups. If the username is a member of any of ConfD
's AAA groups, it will be placed in these groups. Otherwise, if there is a defaultGroup configured in
confd.conf , the user will be placed in this group. Otherwise, the user does not belong to any group.
Note that the user is authenticated by the SNMP agent, and not by ConfD 's AAA.
For each SNMP object the user tries to access, VACM is consulted to see if the user's securityName
has access. If it has, the SNMP agent will try to access the corresponding YANG object. ConfD 's
normal AAA authorization is consulted to see if the groups the user belongs to have access to the
YANG object.
Since both VACM and ConfD 's AAA are consulted, a ConfD user can choose to use one of them,
or both. One usage strategy can be to add VACM rules which gives full access to everyone, and then
rely on ConfD 's AAA rules. Anther strategy could be to have detailed rules in VACM, and then give
full access to the "snmp" context in ConfD 's AAA.
ConfD High Availability
If ConfD is run in HA mode, the SNMP variables sysUpTime, snmpEngineTime, and
snmpEngineBoots are automatically replicated. This means that if a slave ConfD takes over as
master, these variables will keep their values.
It is essential that each ConfD instance in the cluster has the same snmpEngineID configured. This
value is defined in confd.conf , and it is the responsibility of the user to make sure it has the
same value on all nodes in the cluster. However, if ConfD 's configuration is stored in CDB (see
Section 23.4.2, “Storing ConfD configuration parameters in CDB”), then since CDB is replicated, the
snmpEngineID will always be the same in the cluster.
