Access Control

The netconfd-pro access control data model is defined in ietf-netconf-acm.yang (RFC 8341)

• Access control is applied to the server content. Authentication and admission control has already been done.

• Every client session must have a user-name to use access control.

• Any user-name configured as a --superuser is exempt from NACM access control, even in 'enforcing' mode.

  • The superuser account should not be used in normal operation.

  • It is called a 'recovery' user in the standard.

  • If NACM is used, then is is a good idea to have at least one superuser configured to allow a 'broken' NACM configuration to be changed.

• Access control is not applied to internal operations from DB-API unless requested by the application.

• The server has many security enhancements in addition to NACM, such as password protection and user-write restrictions.

Example Access Denied Error

If NACM denies access for any access mode except 'read' then an error is returned to the client.

<rpc-reply message-id="5" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <rpc-error>
  <error-type>protocol</error-type>
  <error-tag>access-denied</error-tag>
  <error-severity>error</error-severity>
  <error-app-tag>no-access</error-app-tag>
  <error-message xml:lang="en">access denied</error-message>
  <error-info>
   <error-number>267</error-number>
  </error-info>
 </rpc-error>
</rpc-reply>

Access Control Defaults

The --access-control CLI parameter is set to enforcing by default. This setting MUST be used to fully interoperate with the NACM standard.

NACM has special rules and YANG extensions for controlling default access to server operations and content.

NACM Global Configuration Leafs

module: ietf-netconf-acm
     +--rw nacm
        +--rw enable-nacm?              boolean
        +--rw read-default?             action-type
        +--rw write-default?            action-type
        +--rw exec-default?             action-type
        +--rw enable-external-groups?   boolean

NACM Security Profiles

The examples in this section refer to 'normal security' or 'high security'. This refers to the settings used for the 3 NACM configuration leafs:

NACM Setting	Normal Security	High Security
read-default	permit	deny
write-default	deny	deny
exec-default	permit	deny

• Normal Security Profile

  • Default is to allow read and exec access

  • Add 'permit' rules to allow any datastore editing

  • Add 'deny' rules to disallow any specific read or exec access

• High Security Profile

  • Default is to disallow all access

  • Add 'permit' rules to allow any type of access

read-default

This leaf controls all YANG data read access, which includes retrieval operations and notification data.

Warning

• Changing this setting to deny may prevent proper server operation with a standard NETCONF or RESTCONF client.

The 'read-default' leaf has a default value of permit. If this value is set to deny, then explicit access rules will be required for any non-superuser client session.

Refer to the NACM Read Access Examples section for an example that provides a profile that allows this required data.

In particular:

• The ietf-yang-library.yang module must be allowed:

  • This includes the /modules-state subtree, which is required for proper YANG 1.1 operation

  • This includes the /yang-library subtree if the --with-nmda parameter is set to 'true'

• The ietf-netconf-monitoring.yang module should be allowed:

  • The /netconf-state subtree is required by the NETCONF standard

  • The <get-schema> operation is required by the NETCONF standard

• The ietf-restconf-monitoring.yang module should be allowed if the --with-restconf parameter is set to 'true':

  • The /restconf-state subtree is required by the RESTCONF standard

• The nc-notifications.yang module must be allowed if the --with-notifications parameter is set to 'true'.

  • This module provides the /netconf subtree used for RFC 5277 notifications

There may additional YANG modules that need read access permitted in order for the server to operate correctly.

• For 'normal' security this leaf should be set to permit.

  • The YANG module should use the nacm:default-deny-write or nacm:default-deny-all extension to block read access to sensitive data.

  • For other data nodes, explicit access control rules should be added to block read access to the specified data.

• For 'high' security this leaf should be set to deny.

  • Any data that is defined with the nacm:default-deny-write or nacm:default-deny-all extension is already blocked and requires explicit rules to allow any read access.

  • For other data nodes, explicit access control rules should be added to permit read access.

write-default

This leaf controls all YANG configuration datastore write access. NACM protects the conceptual datastore, so the actual protocol operation used to alter the configuration does not matter.

The 'write-default' leaf is set to deny by default.

Warning

Changing this setting to permit is not recommended.

There are no standard protocol operations that require write access to a configuration datastore.

• For 'normal' and 'high' security this leaf should be set to deny.

  • For all data nodes, explicit access control rules should be added to permit write access.

Refer to the NACM Write Access Examples section for examples of write access rules.

exec-default

This leaf controls all RPC operation and YANG action execution access.

The 'exec-default' leaf is set to permit by default.

Warning

Changing this setting to deny is not recommended.

If this value is set to deny, then explicit access rules will be required for any non-superuser client session.

In particular, some operations must be enabled for any non-superuser session to operate correctly:

• <close-session>

• <get>

• <get-config>

• <get-data> (if --with-nmda parameter set to 'true')

• <get-schema>

All other protocol operations and all YANG options are optional to enable, depending on the server configuration.

• For 'normal' security this leaf should be set to permit.

  • The YANG module should use the nacm:default-deny-all extension to block execution access to sensitive operations.

  • For other operations, explicit access control rules should be added to block execution access to the specified operation.

  • For YANG actions, explicit access control rules could be added to block read access to the ancestor nodes of the YANG action. This also blocks execution access.

• For 'high' security this leaf should be set to deny.

  • Access control rules to permit the session to close and read mandatory data must be defined.

  • For all other operations and all YANG actions, explicit access control rules should be added to permit execution access.

Refer to the NACM Exec Access Examples section for examples of exec access rules.

NACM Default Overrides Using Extensions

The nacm:default-deny-write and nacm:default-deny-all extensions also affect access control. If present in the YANG definition, then the default behavior (when no rule is found) is not followed. Instead, a superuser account or explicit NACM rule must be used to allow any access at all.

Refer to the Special YANG Extensions For Access Control section for more information of these extensions.

Refer to the YANG Extensions Affecting Passwords section for more extensions.

NACM Configuration Overview

The NACM configuration data model is documented in RFC 8341.

Access Control Rules

The NACM data model can be used without any configuration at all. Refer to the Access Control Modes section for more details.

Normally, some configuration is required:

• groups: configure one or more local administrative groups

  • no local groups are required if external groups are used

• rule-lists: configure one or more access control rules for each rule-list

  • rule-lists and the rules within each rule-list are user-ordered and the first match found is used when processing client requests.

  • more specific rule-lists and rules need to be ordered before less specific ones.

  • 'module-name' leaf: module-specific rules must be found before any rule that uses the the wildcard '*' value.

  • 'rule-type' choice: any rules configuring a case in this choice must be found before any rule that omits this choice

The entire /nacm subtree is tagged as nacm:default-deny-all. By default, only a superuser account can read or write any of the /nacm contents. It is suggested that even read access to this data structure be controlled carefully at all times.

The /nacm subtree is described in the ietf-netconf-acm.yang section and RFC 8341.

Bypassing Access Control

By default, no configuration data can be edited. Even if the NACM write-default is set to permit, the /nacm subtree cannot be edited by default.

The --superuser CLI parameter can be used to allow the specified user sessions to bypass NACM enforcement. This can be used to configure NACM groups and rule-lists, and access all API components normally protected by NACM.

Access control can also be completely disabled by setting the --access-control CLI parameter to off. This is not recommended!

Enabling and Disabling NACM

The /nacm/enable-nacm leaf can be used to enable or disable the enforcement of NACM procedures.

The --access-control parameter must be set to 'enforcing' for this NACM leaf to function properly.

All groups and rule-lists remain in place if this parameter is set to 'false'.

Access Control Modes

The --access-control configuration parameter is used to globally enable or disable the access control system. It cannot be changed at run-time, or through a NETCONF session.

• off: no access control enforcement is done at all.

• disabled: all nacm:default-deny-write and nacm:default-deny-all tagged objects will require a superuser account to access, but no other access control enforcement will be done.

• permissive: all nacm:default-deny-all objects will require super user account to read. No other read access enforcement will be done. Write and exec access will be checked.

• enforcing: all access control enforcement will be checked. This is the default behavior.

Permissions

There are 3 types of access permissions defined:

1. read: retrieval of any kind

2. write: modification of any kind

3. exec: right to invoke an RPC operation

The <allowed-rights> object in each of the 3 access control rule entries is a 'bits' leaf, which is allowed to contain any of these string tokens, or none of them to deny all access to a set of groups.

When a rule is found which matches the current request, the <allowed-rights> leaf will be used to grant permission or not. If the bit for the requested operation is present, then the request is permitted. If the bit is not present, then the request is denied.

Users and Groups

Access rights in NACM are given to groups.

A group entry consists of a group identifier and a list of user names that are members of the group.

By default, there are no groups created. Each /nacm/groups/group entry must be created by the client. There is no user name table either. It is assumed that the operator will know which user names are valid within each managed device.

Creating New Groups

The <edit-config> operation can be used to create new group entries.

• A user name can appear within the same group zero or one times.

• A user name can appear in zero or more groups.

When a user is a member of multiple groups, all these groups will be used to match against rules, in a conceptual 'OR' expression. If any of these groups matches one of the <allowed-group> leaf-list nodes within one of the 3 rule types, then that rule will be the one that is used. Rules are always searched in the order they are entered, even the system-ordered lists.

The path to the group element is /nacm:nacm/nacm:groups/nacm:group.

The following <edit-config> example shows how a group can be defined. The group name is 'admi1',and the users 'user1' and 'user2' are the initial members of this group.

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
            nc:operation="merge">
            <name>admin1</name>
            <user-name>user1</user-name>
            <user-name>user2</user-name>
          </group>
        </groups>
      </nacm>
    </config>
  </edit-config>
</rpc>

NACM External Groups

NACM supports external 'user-name to group-name' mappings. If the /nacm/enable-external-groups leaf is set to 'true' and the NACM External Groups Callback is used, then the external groups are checked and the locally configured groups are also checked.

leaf enable-external-groups {
  type boolean;
  default "true";
  description
    "Controls whether the server uses the groups reported by the
     NETCONF transport layer when it assigns the user to a set of
     NACM groups.  If this leaf has the value 'false', any group
     names reported by the transport layer are ignored by the
     server.";
}

The default for this leaf is 'true', but it is ignored unless a NACM External Groups Callback is registered. This callback is used to get the group membership list for a session user-name.

NACM Groups Example

The following configuration show how two groups can be used to separate advanced and basic server access.

• NACM groups are usually defined to represent the administrative role of the group.

• Any number of groups can be used, not just one or two.

• No groups are requires unless any /nacm/rule-list entries are configured

<data>
  <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
   <groups>
    <group>
     <name>admin</name>
     <user-name>admin1</user-name>
    </group>
    <group>
     <name>guest</name>
     <user-name>netconf1</user-name>
     <user-name>guest</user-name>
    </group>
   </groups>
  </nacm>
 </data>

Using Access Control Rules

Quick Summary:

• Users belong to groups

• Rule-lists apply to groups (who is accessing?)

• Rules apply to server API content (what is being accessed?)

• Actions are applied when a rule is found (permit or deny)

• If no rule applies, then the default handling rules apply

NACM Rule Lists

The NACM data model has a configuration list called /nacm/rule-list.

• This is the main part of the NACM configuration.

• The server goes through the rule-list in order when enforcing NACM procedures.

• A user-name must be configured in at least one group in order for any rule-list to apply to sessions for that user.

• A rule-list is said to match if the user-name for the session is in one of the groups for the rule-list.

• A rule-list with no 'group' entries will always be skipped.

• For each leaf-list /nacm/rule-list/group entry:

  • If group == '*' then user-name must be in at least one group

  • If group != '*' then user-name must be in the specific group

NACM also supports external 'user-name to group-name' mappings.

• If the /nacm/enable-external-groups leaf is set to 'true' and the NACM External Groups Callback is used, then the external groups are checked and the configured 'group' list (if any) are also used.

• The rule-list processing stops as soon as a matching rule-list is found or no more /nacm/groups/group entries to check.

  • If group found then the /nacm/rule-list/rule list is checked

  • If group not found then continue to the next rule-list entry

Rule-List Example

• An empty rule list for the 'admin' group is created

• An empty rule list for the 'guest' group is created

• Both groups apply to the default (all modules)

<data>
  <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
   <rule-list>
    <name>admin-rules</name>
    <group>admin</group>
   </rule-list>
   <rule-list>
    <name>guest-rules</name>
    <group>guest</group>
   </rule-list>
  </nacm>
 </data>

NACM Rules

Within each rule-list is an ordered set of access control rules.

• If 'module-name' == '*' then the rule applies to all modules

• If 'module-name' != '*' then the rule applies to only that module

If the module containing the YANG definition for the notification, data node, operation, or action being accessed matches then the rest of the rule is checked. Otherwise the next rule is checked.

The 'rule-type' choice is optional.

• If missing then the rule applies to all content from the matching module.

• If configured then only the specified requests are checked

To configure a 'rule-type', provide one of the 4 leaf options:

• rpc-name to limit the rule to RPC operations and YANG actions

• notification-name to limit the rule to notification event types

• path to limit the rule to the specified data node instances

• module-tag to limit the rule to all matches of the specified module tag. This is non-standard, and only available if the --with-modtags parameter is set to 'true'.

If a rule matches the rule-type (or no rule-type) then the 'access-operations' leaf is checked:

• If 'access-operation' == '*' then the rule always applies

• If 'access-operation' != '*' then the rule applies only if the requested operation is in the bit set:

  • create

  • read

  • update

  • delete

  • exec

Finally, if the rule applies then the processing is complete, and the 'action' is followed.

• For 'read' access:

  • permit: allow the operation

  • deny: omit the data from the read response or drop the notification event

• For all other access:

  • permit: allow the operation or write access

  • deny: reject the access and return an 'rpc-error'

Refer to the NACM Usage Examples section for more details on using NACM rule-lists and rules to control access to the server.

Special YANG Extensions For Access Control

There are 3 YANG language extensions defined that can be used to force access control behavior for specific data nodes in the configuration database.

1. nacm:default-deny-write (no parameter) If present in a data node statement, this extension will cause the write default to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

2. nacm:default-deny-all (no parameter) If present in a data node statement, this extension will cause the read and write defaults to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. Read access will be denied, which causes that data to be removed from the <rpc-reply>. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

3. ncx:user-write (parameter: permitted, type: bits: create, update, delete) Used within database configuration data definition statements to control user write access to the database object containing this statement. The 'permitted' argument is a list of operations that users are permitted to invoke for the specified node. These permissions will over-ride all NACM access control rules, even if NACM is disabled. To dis-allow all user access, provide an empty string for the 'permitted' parameter.

   To allow only create and delete user access, provide the string 'create delete' for the parameter. Use this for YANG database objects that cannot be changed once they are set.

Access Control Algorithm

The access control enforcement procedures are defined in RFC 8341, section 3.4

NACM Usage Examples

Grant All Access to a Group

Note

• This rule-list provides the same access as a --superuser.

• More strict access control should be considered instead.

In this example, the 'admin' group is granted all access.

<rule-list>
  <name>grant-all</name>
  <group>admin</group>
  <rule>
   <name>rule1</name>
   <module-name>*</module-name>
   <access-operations>*</access-operations>
   <action>permit</action>
   <comment>Admin group has all access</comment>
  </rule>
 </rule-list>

Grant All Exec Access to a Group

In this example, the 'admin' group is granted all exec access permission only.

<rule-list>
  <name>grant-all-exec</name>
  <group>admin</group>
  <rule>
   <name>rule1</name>
   <module-name>*</module-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec access to all operations and actions</comment>
  </rule>
 </rule-list>

NACM Read Access Examples

There must be NACM rules to grant exec access for any data not allowed by the read-default or because the nacm:default-deny-all extension applies to the data node.

Allow Retrieval of Required Operational Data

This example shows the minimum set of YANG sub-trees that should be allowed if the read-default is set to 'false'. The example uses module rules instead of data rules because they are simpler and more efficient to enforce in the server.

Read access is allowed to the following modules:

• ietf-yang-library.yang

• ietf-netconf-monitoring.yang

• ietf-restconf-monitoring.yang

• nc-notifications.yang

<rule-list>
  <name>read-min-data</name>
  <group>admin</group>
  <group>guest</group>
  <rule>
   <name>yanglib-rule</name>
   <module-name>ietf-yang-library</module-name>
   <access-operations>read</access-operations>
   <action>permit</action>
   <comment>Allow read of YANG library data</comment>
  </rule>
  <rule>
   <name>netmon</name>
   <module-name>ietf-netconf-monitoring</module-name>
   <access-operations>read</access-operations>
   <action>permit</action>
   <comment>Allow read of /netconf-state data</comment>
  </rule>
  <rule>
   <name>restmon</name>
   <module-name>ietf-restconf-monitoring</module-name>
   <access-operations>read</access-operations>
   <action>permit</action>
   <comment>Allow read of /restconf-state data</comment>
  </rule>
  <rule>
   <name>notifmon</name>
   <module-name>nc-notifications</module-name>
   <access-operations>read</access-operations>
   <action>permit</action>
   <comment>Allow read of /netconf data</comment>
  </rule>
 </rule-list>

NACM Write Access Examples

In this profile, there are usually 2 types of rules to configure:

• grant write access to configuration data

• grant read or exec access for any data not allowed by the read-default or exec-default because the nacm:default-deny-all extension applies

Grant Write Access to One Module

In this example, write access is given to the ietf-interfaces module using a NACM module-specific rule.

<rule-list>
 <name>write-one-module</name>
 <group>admin</group>
 <rule>
  <name>rule1</name>
  <module-name>ietf-interfaces</module-name>
  <access-operations>create update delete</access-operations>
  <action>permit</action>
  <comment>Allow write access to ietf-interfaces module namespace only</comment>
 </rule>
</rule-list>

Grant Write Access to All Interfaces

In this example, write access is given to the /interfaces subtree using a NACM data rule. The 'module-name' is set to the wildcard in order to allow write access to all the data nodes from other modules that are augmenting the /interfaces/interface list entry.

Note that this example does not properly use XML namespaces and the XPath expression actually matches any top-level node named 'interfaces', not just the container from the ietf-interfaces.yang module.

<rule-list>
  <name>write-all-interfaces</name>
  <group>admin</group>
  <rule>
   <name>rule1</name>
   <module-name>*</module-name>
   <path>/interfaces</path>
   <access-operations>create update delete</access-operations>
   <action>permit</action>
   <comment>Allow write access to the /interfaces subtree</comment>
  </rule>
 </rule-list>

Grant Write Access to One Interface

In this example, write access is given to the subtree for the eno1 interface, using a NACM data rule. The 'module-name' is set to the wildcard in order to allow write access to all the data nodes from other modules that are augmenting the /interfaces/interface list entry.

Note that this example does not properly use XML namespaces and the XPath expression actually matches any top-level node named 'interfaces', not just the container from the ietf-interfaces.yang module.

<rule-list>
 <name>write-one-interface</name>
 <group>admin</group>
 <rule>
  <name>rule1</name>
  <module-name>*</module-name>
  <path>/interfaces/interface[name='eno1']</path>
  <access-operations>create update delete</access-operations>
  <action>permit</action>
  <comment>Allow write access to the 'eno1' interface</comment>
 </rule>
</rule-list>

NACM Exec Access Examples

There must be NACM rules to grant exec access for any operation or action not allowed because the ref:exec-default parameter is 'false' or because the nacm:default-deny-all extension applies to the RPC operation or YANG action.

Allow Execution of Required Operations

This example shows the minimum set of RPC operations that should be allowed if the exec-default is set to 'false'. The 'get-data-rule' is only required if the --with-nmda parameter is set to 'true'.

<rule-list>
  <name>exec-min-operations</name>
  <group>admin</group>
  <group>guest</group>
  <rule>
   <name>close-rule</name>
   <module-name>ietf-netconf</module-name>
   <rpc-name>close-session</rpc-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec of the close-session operation</comment>
  </rule>
  <rule>
   <name>get-rule</name>
   <module-name>ietf-netconf</module-name>
   <rpc-name>get</rpc-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec of the get operation</comment>
  </rule>
  <rule>
   <name>get-config-rule</name>
   <module-name>ietf-netconf</module-name>
   <rpc-name>get-config</rpc-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec of the get-config operation</comment>
  </rule>
  <rule>
   <name>get-data-rule</name>
   <module-name>ietf-netconf-nmda</module-name>
   <rpc-name>get-data</rpc-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec of the get-data operation</comment>
  </rule>
  <rule>
   <name>get-schema-rule</name>
   <module-name>ietf-netconf-monitoring</module-name>
   <rpc-name>get-schema</rpc-name>
   <access-operations>exec</access-operations>
   <action>permit</action>
   <comment>Allow exec of the get-schema operation</comment>
  </rule>
 </rule-list>

Allow Execution of Protected Operations

This example shows some RPC operations that could be allowed for 'admin' access. The are protected by the nacm:default-deny-all extension so they cannot be executed even if exec-default is set to 'true'.

<rule-list>
 <name>exec-protected-operations</name>
 <group>admin</group>
 <rule>
  <name>delete-rule</name>
  <module-name>ietf-netconf</module-name>
  <rpc-name>delete-config</rpc-name>
  <access-operations>exec</access-operations>
  <action>permit</action>
  <comment>Allow exec of the delete-config operation</comment>
 </rule>
 <rule>
  <name>kill-rule</name>
  <module-name>ietf-netconf</module-name>
  <rpc-name>kill-session</rpc-name>
  <access-operations>exec</access-operations>
  <action>permit</action>
  <comment>Allow exec of the kill-session operation</comment>
 </rule>
</rule-list>

Using Module Tags with NACM

There is a "module-tag" extension to NACM defined in yumaworks-system.yang

augment /nacm:nacm/nacm:rule-list/nacm:rule/nacm:rule-type {
  case module-tags {
    uses ywapp:ModuleTagParm;
  }
}

This extension adds a new rule-type called module-tags.

A list of module-tag strings can be used to select the modules that are mapped to the NACM rule.

It is similar to a data-rule which selects a path, except it selects all objects from the specified module(s) for RPC, notification, and data node access control.

Module-tags are more flexible than the module-name leaf provided in the NACM rule entry.

It is recommended that this field be set to the default ‘*’ if the module-tag parameter is used.

Example:

The following module-tag is used:

module-tagmap ietf-restconf-monitoring@restconf

The module ietf-restconf-monitoring is mapped to the module-tag “restconf”.

The following NACM configuration contains a module-tags rule:

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
  <read-default>deny</read-default>
    <groups>
      <group>
        <name>g1</name>
        <user-name>netconf1</user-name>
      </group>
    </groups>
  <rule-list>
    <name>rl1</name>
    <group>g1</group>
    <rule>
      <name>r1</name>
      <module-name>*</module-name>
      <access-operations>*</access-operations>
      <action>permit</action>
      <comment/>
      <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">restconf</module-tag>
    </rule>
  </rule-list>
</nacm>

This rule allows group “g1” all access to the modules tagged with the module-tag “restconf”.

An example <get> request returns only the data from the ietf-restconf-monitoring.yang module.

netconf1@localhost> get

RPC Data Reply 3 for session 4 [default]:

rpc-reply {
  data {
    restconf-state {
      capabilities {
        capability urn:ietf:params:restconf:capability:depth:1.0
        capability urn:ietf:params:restconf:capability:with-defaults:1.0
        capability urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=report-all
        capability urn:ietf:params:restconf:capability:fields:1.0
        capability urn:ietf:params:restconf:capability:replay:1.0
        capability urn:ietf:params:restconf:capability:filter:1.0
        capability urn:ietf:params:restconf:capability:yang-patch:1.0
      }
      streams {
        stream RESTCONF {
          name RESTCONF
          description 'default RESTCONF event stream'
          replay-support true
          replay-log-creation-time 2018-04-27T21:45:56Z
          access xml {
            encoding xml
            location http://localhost/restconf/stream
          }
        }
      }
    }
  }
}

NACM Access Denial Monitoring

The NACM standard provides a few counters to monitor that increment when NACM denies a client session the requested access.

module: ietf-netconf-acm
   +--rw nacm
      +--ro denied-operations         yang:zero-based-counter32
      +--ro denied-data-writes        yang:zero-based-counter32
      +--ro denied-notifications      yang:zero-based-counter32

NACM Access Denial Audit Log

The audit log allows certain events to be logged independently of the other logging channels.

• Created by default if --fileloc-fhs is set to 'true' and --no-audit-log parameter is not present.

• Created if --audit-log parameter is set

Example Config For Audit Log Use

audit-log ~/audit.log
audit-log-events "edit-running acm-write-error acm-exec-error"
audit-log-candidate false

Example Error and Audit Log for Write Denied Error

In this example, the 'netconf1' user attempts to create some NACM configuration data. This is restricted and a 'no-access' error is returned.

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <rpc-error>
  <error-type>protocol</error-type>
  <error-tag>access-denied</error-tag>
  <error-severity>error</error-severity>
  <error-app-tag>no-access</error-app-tag>
  <error-message xml:lang="en">access denied</error-message>
  <error-info>
   <error-number>267</error-number>
  </error-info>
 </rpc-error>
</rpc-reply>

At the same time, a new entry is created in the audit log:

nacm-write-error:
  time: 2023-08-08T21:23:29Z
  username: netconf1
  operation: merge container nacm
  path:: /nacm:nacm

Example Error and Audit Log for Operation Denied Error

In this example, the 'netconf1' user attempts to invoke the <kill-session> operation. This is restricted and a 'no-access' error is returned.

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="6" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
 xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <rpc-error>
  <error-type>rpc</error-type>
  <error-tag>access-denied</error-tag>
  <error-severity>error</error-severity>
  <error-app-tag>no-access</error-app-tag>
  <error-path>/nc:rpc/nc:kill-session</error-path>
  <error-message xml:lang="en">access denied</error-message>
  <error-info>
   <error-number>267</error-number>
  </error-info>
 </rpc-error>
</rpc-reply>

At the same time, a new entry is created in the audit log:

nacm-exec-error:
  time: 2023-08-08T21:30:20Z
  username: netconf1
  module name: ietf-netconf
  RPC name: kill-session

NACM Access Troubleshooting

There are essentially 3 types of mis-configuration issues that can occur:

• Rule to control some access that should get applied is not getting applied

• Rule to control some access that should not get applied is getting applied

• The correct rule is getting applied but it is not working

The server can generate log entries that show how access control is applied for the operation. These log messages can often identify why the NACM rule-lists and rules are not working correctly.

Enable NACM Logging

There is more debug information available in the 'debug' builds but NACM logging is available even if PRODUCTION=1 is used to build the server.

To enable NACM debug messages the --log-level parameter must be set to debug2, debug3, or debug4.

The debug logging messages are usually only done for 'exec' and write access. There are usually no logging messages printed for denied read access, unless a rule is applied for the access. No logging is produced if the read-default is used.

> netconfd-pro --log-level=debug2

PERMIT or DENY Logging Entry

There will be some terse NACM logging messages of the form:

agt_acm: PERMIT (reason)

agt_acm: DENY (reason)

If a NACM rule is applied to determine the access result, then it will be printed in the logging output if log level is set to debug4.

• Check if the default was applied or a rule applied. E.g. (write-default)

• Check if a rule was applied. By determining which rule was applied. The order or rules may need to be changed.

• If a rule was skipped that should have been applied, make sure that all the conditions are met for the rule.

• If a rule was not reached that should have been applied:

  • check if the rule order needs to be changed.

  • check if the rule that matched is not specific enough, such as module-name='*' and should be a specific module

Example NACM Logging for the Superuser

If the superuser account is used, then the log entries may appear as follows:

agt_acm: check <get> RPC allowed for user 'andy'
agt_acm: PERMIT (superuser)

Example NACM Logging for the Admin User

The 'grant-all' rule should apply to all 'admin' group members.

For example, if the 'admin1' user retrieved the /nacm subtree then the following log entries might appear, if the log level is set to debug4.

agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:nacm'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:denied-operations'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:denied-data-writes'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:denied-notifications'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:groups'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:group'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:user-name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:user-name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:group'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:user-name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:user-name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:rule-list'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:group'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:rule'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:module-name'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:access-operations'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:action'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:comment'

If 'admin1' creates configuration data, then the following log entries may appear:

The following example shows the logging output for debug2:

***** start validate phase on candidate for session 5, transaction 64 *****

agt_acm: check write <nacm> allowed for user 'admin1'
agt_acm: PERMIT write (rule-list)
agt_acm: check write <groups> allowed for user 'admin1'
agt_acm: PERMIT write (rule-list)
agt_acm: check write <group> allowed for user 'admin1'
agt_acm: PERMIT write (rule-list)
agt_acm: check write <name> allowed for user 'admin1'
agt_acm: PERMIT write (rule-list)

The actual rule that matched is not printed. This is only done if the log level is set to debug4.

agt_acm: check write <nacm> allowed for user 'admin1'
agt_acm: applying rule 'grant-all/rule1' for request on ietf-netconf-acm:nacm'
agt_acm: PERMIT write (rule-list)

Example NACM Logging for Write Denied

If a user is denied access to a data node during processing of an <edit-config> or other edit operation, then the log entries may appear as follows:

agt_acm: check write <nacm> allowed for user 'netconf1'
agt_acm: DENY write (write-default)

Extended NACM Logging

If the server is built with the DEBUG=1 and DEBUG2=1 make flags, then the agt_acm_ietf.c module will generate extended logging information about the rule-list processing. In addition, the log level must be set to debug3 or debug4 in order for the extra logging messages to be printed.