ConfD!!

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:

admin

99

bob joe

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:

101

http://tail-f.com/ns/aaa/1.1

cli

/aaa/authentication/users/user[name='bob']/password

admin

rw

accept

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:

101

http://tail-f.com/ns/aaa/1.1

cli

/aaa/authentication/users/user[name='bob']/password

admin

rw

accept

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.