Configuration file format¶

The initial state of NFD is configured using a textual file in Boost INFO format.

; The general section contains settings of nfd process.
general
{
  ; Specify a user and/or group for NFD to drop privileges to
  ; when not performing privileged tasks. NFD does not drop
  ; privileges by default.

  ; user ndn-user
  ; group ndn-user
}

log
{
  ; default_level specifies the logging level for modules
  ; that are not explicitly named. All debugging levels
  ; listed above the selected value are enabled.
  ;
  ; Valid values:
  ;
  ;  NONE ; no messages
  ;  ERROR ; error messages
  ;  WARN ; warning messages
  ;  INFO ; informational messages (default)
  ;  DEBUG ; debugging messages
  ;  TRACE ; trace messages (most verbose)
  ;  ALL ; all messages

  default_level INFO

  ; You may override default_level by assigning a logging level
  ; to the desired module name. Module names can be found in two ways:
  ;
  ; Run:
  ;   nfd --modules
  ;
  ; Or look for NFD_LOG_INIT(<module name>) statements in source files.
  ; Note that the "nfd." prefix can be omitted.
  ;
  ; Example module-level settings:
  ;
  ; FibManager DEBUG
  ; Forwarder INFO
}

; The tables section configures the CS, PIT, FIB, Strategy Choice, and Measurements
tables
{
  ; ContentStore size limit in number of packets
  ; default is 65536, about 500MB with 8KB packet size
  cs_max_packets 65536

  ; Set the CS replacement policy.
  ; Available policies are: priority_fifo, lru
  cs_policy lru

  ; Set a policy to decide whether to cache or drop unsolicited Data.
  ; Available policies are: drop-all, admit-local, admit-network, admit-all
  cs_unsolicited_policy drop-all

  ; Set the forwarding strategy for the specified prefixes:
  ;   <prefix> <strategy>
  strategy_choice
  {
    /               /localhost/nfd/strategy/best-route
    /localhost      /localhost/nfd/strategy/multicast
    /localhost/nfd  /localhost/nfd/strategy/best-route
    /ndn/broadcast  /localhost/nfd/strategy/multicast
  }

  ; Declare network region names
  ; These are used for mobility support.  An Interest carrying a Link object is
  ; assumed to have reached the producer region if any delegation name in the
  ; Link object is a prefix of any region name.
  network_region
  {
    ; /example/region1
    ; /example/region2
  }
}

; The face_system section defines what faces and channels are created.
face_system
{
  ; This section contains options that apply to multiple face protocols.
  general
  {
    enable_congestion_marking yes ; set to 'no' to disable congestion marking on supported faces, default 'yes'
  }

  ; The unix section contains settings for Unix stream faces and channels.
  ; A Unix channel is always listening; delete the unix section to disable
  ; Unix stream faces and channels.
  unix
  {
    ; The default transport is unix:///run/nfd.sock (on Linux) or unix:///var/run/nfd.sock (on
    ; other platforms). This should match the "transport" field in client.conf for ndn-cxx. If you
    ; wish to use TCP instead of Unix sockets with ndn-cxx, change "transport" to an appropriate
    ; TCP FaceUri.
    path /run/nfd.sock ; Unix stream listener path
  }

  ; The tcp section contains settings for TCP faces and channels.
  tcp
  {
    listen yes ; set to 'no' to disable TCP listener, default 'yes'
    port 6363 ; TCP listener port number
    enable_v4 yes ; set to 'no' to disable IPv4 channels, default 'yes'
    enable_v6 yes ; set to 'no' to disable IPv6 channels, default 'yes'

    ; A TCP face has local scope if the local and remote IP addresses match the whitelist but not the blacklist
    local
    {
      whitelist
      {
        subnet 127.0.0.0/8
        subnet ::1/128
      }
      blacklist
      {
      }
    }
  }

  ; The udp section contains settings for UDP faces and channels.
  udp
  {
    ; UDP unicast settings.
    listen yes ; set to 'no' to disable UDP listener, default 'yes'
    port 6363 ; UDP listener port number
    enable_v4 yes ; set to 'no' to disable IPv4 channels, default 'yes'
    enable_v6 yes ; set to 'no' to disable IPv6 channels, default 'yes'

    ; Time (in seconds) before closing an idle UDP unicast face.
    ; The actual timeout will occur anytime between idle_timeout and 2*idle_timeout.
    ; The default is 600 (10 minutes).
    idle_timeout 600

    ; UDP multicast settings.
    ; By default, NFD creates one UDP multicast face per NIC.
    ;
    ; In multi-homed Linux machines these settings will NOT work without
    ; root or setting the appropriate permissions:
    ;
    ;    sudo setcap cap_net_raw=eip /path/to/nfd
    ;
    mcast yes ; set to 'no' to disable UDP multicast, default 'yes'
    mcast_group 224.0.23.170 ; UDP multicast group (IPv4)
    mcast_port 56363 ; UDP multicast port number (IPv4)
    mcast_group_v6 ff02::1234 ; UDP multicast group (IPv6)
    mcast_port_v6 56363 ; UDP multicast port number (IPv6)
    mcast_ad_hoc no ; set to 'yes' to make all UDP multicast faces "ad hoc", default 'no'

    ; Whitelist and blacklist can contain, in no particular order:
    ; - interface names, including wildcard patterns (e.g., 'ifname eth0', 'ifname en*', 'ifname wlp?s0')
    ; - MAC addresses (e.g., 'ether 85:3b:4d:d3:5f:c2')
    ; - IPv4 subnets (e.g., 'subnet 192.0.2.0/24')
    ; - IPv6 subnets (e.g., 'subnet 2001:db8::/32')
    ; - a single asterisk ('*') that matches all interfaces
    ; By default, all interfaces are whitelisted.
    whitelist
    {
      *
    }
    blacklist
    {
    }
  }

  ; The ether section contains settings for Ethernet faces and channels.
  ; These settings will NOT work without root or setting the appropriate
  ; permissions:
  ;
  ;    sudo setcap cap_net_raw,cap_net_admin=eip /path/to/nfd
  ;
  ; You may need to install a package to use setcap:
  ;
  ; **Ubuntu:**
  ;
  ;    sudo apt install libcap2-bin
  ;
  ; **Mac OS X:**
  ;
  ;    curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
  ;    tar zxvf ChmodBPF.tar.gz
  ;    open ChmodBPF/Install\ ChmodBPF.app
  ;
  ; or manually:
  ;
  ;    sudo chgrp admin /dev/bpf*
  ;    sudo chmod g+rw /dev/bpf*
  ;
  ether
  {
    ; Ethernet unicast settings.
    listen yes ; set to 'no' to disable Ethernet listener, default 'yes'

    ; Time (in seconds) before closing an idle Ethernet unicast face.
    ; The actual timeout will occur anytime between idle_timeout and 2*idle_timeout.
    ; The default is 600 (10 minutes).
    idle_timeout 600

    ; Ethernet multicast settings.
    ; By default, NFD creates one Ethernet multicast face per NIC.
    mcast yes ; set to 'no' to disable Ethernet multicast, default 'yes'
    mcast_group 01:00:5E:00:17:AA ; Ethernet multicast group
    mcast_ad_hoc no ; set to 'yes' to make all Ethernet multicast faces "ad hoc", default 'no'

    ; Whitelist and blacklist can contain, in no particular order:
    ; - interface names, including wildcard patterns (e.g., 'ifname eth0', 'ifname en*', 'ifname wlp?s0')
    ; - MAC addresses (e.g., 'ether 85:3b:4d:d3:5f:c2')
    ; - IPv4 subnets (e.g., 'subnet 192.0.2.0/24')
    ; - IPv6 subnets (e.g., 'subnet 2001:db8::/32')
    ; - a single asterisk ('*') that matches all interfaces
    ; By default, all interfaces are whitelisted.
    whitelist
    {
      *
    }
    blacklist
    {
    }
  }

  ; The websocket section contains settings for WebSocket faces and channels.
  websocket
  {
    listen yes ; set to 'no' to disable WebSocket listener, default 'yes'
    port 9696 ; WebSocket listener port number
    enable_v4 yes ; set to 'no' to disable listening on IPv4 socket, default 'yes'
    enable_v6 yes ; set to 'no' to disable listening on IPv6 socket, default 'yes'
  }

  ; The netdev_bound section defines faces bound to netdevices.
  netdev_bound
  {
    ; A rule consists of a whitelist, a blacklist, and a set of remote FaceUris, and will cause the
    ; creation of zero or more faces bound to netdevices. One face will be created per accepted
    ; netdev per remote. There can be any number of rules in the netdev_bound section.

    ; rule
    ; {
    ;   ; Remote FaceUri to which the netdev-bound faces will connect.
    ;   ; Rule can contain multiple remotes. One face will be created for each remote.
    ;   ; All FaceUris must be in canonical form. Currently only udp4 and udp6 are supported.
    ;   remote udp4://192.0.2.1:6363
    ;
    ;   ; Whitelist and blacklist can contain, in no particular order:
    ;   ; - interface names, including wildcard patterns (e.g., 'ifname eth0', 'ifname en*', 'ifname wlp?s0')
    ;   ; - MAC addresses (e.g., 'ether 85:3b:4d:d3:5f:c2')
    ;   ; - IPv4 subnets (e.g., 'subnet 192.0.2.0/24')
    ;   ; - IPv6 subnets (e.g., 'subnet 2001:db8::/32')
    ;   ; - a single asterisk ('*') that matches all interfaces
    ;   ; By default, all interfaces are whitelisted.
    ;   whitelist
    ;   {
    ;     *
    ;   }
    ;   blacklist
    ;   {
    ;   }
    ; }
  }
}

; The authorizations section grants privileges to authorized keys.
authorizations
{
  ; An authorize section grants privileges to a NDN certificate.
  authorize
  {
    ; If you do not already have NDN certificate, you can generate
    ; one with the following commands.
    ;
    ; 1. Generate and install a self-signed identity certificate:
    ;
    ;      ndnsec-keygen /`whoami` | ndnsec-install-cert -
    ;
    ; Note that the argument to ndnsec-key will be the identity name of the
    ; new key (in this case, /your-username). Identities are hierarchical NDN
    ; names and may have multiple components (e.g. `/ndn/ucla/edu/alice`).
    ; You may create additional keys and identities as you see fit.
    ;
    ; 2. Dump the NDN certificate to a file:
    ;
    ;      sudo mkdir -p /usr/local/etc/ndn/keys/
    ;      ndnsec-cert-dump -i /`whoami` >  default.ndncert
    ;      sudo mv default.ndncert /usr/local/etc/ndn/keys/default.ndncert
    ;
    ; The "certfile" field below specifies the default key directory for
    ; your machine. You may move your newly created key to the location it
    ; specifies or path.

    ; certfile keys/default.ndncert ; NDN identity certificate file
    certfile any ; "any" authorizes command interests signed under any certificate,
                 ; i.e., no actual validation.
    privileges ; set of privileges granted to this identity
    {
      faces
      fib
      cs
      strategy-choice
    }
  }

  ; You may have multiple authorize sections that specify additional
  ; certificates and their privileges.

  ; authorize
  ; {
  ;   certfile keys/this_cert_does_not_exist.ndncert
  ;   authorize
  ;   privileges
  ;   {
  ;     faces
  ;   }
  ; }
}

rib
{
  ; The following localhost_security allows anyone to register routing entries in local RIB
  localhost_security
  {
    trust-anchor
    {
      type any
    }
  }

  ; localhop_security should be enabled when NFD runs on a hub.
  ; "/localhop/nfd/fib" command prefix will be disabled when localhop_security section is missing.
  ; localhop_security
  ; {
  ;   ; This section defines the trust model for NFD RIB Management. It consists of rules and
  ;   ; trust-anchors, which are briefly defined in this file.  For more information refer to
  ;   ; validator configuration file format documentation:
  ;   ;
  ;   ;    https://named-data.net/doc/ndn-cxx/current/tutorials/security-validator-config.html
  ;   ;
  ;   ; A trust-anchor is a pre-trusted certificate.  This can be any certificate that is the
  ;   ; root of certification chain (e.g., NDN testbed root certificate) or an existing
  ;   ; default system certificate `default.ndncert`.
  ;   ;
  ;   ; A rule defines conditions a valid packet MUST have. A packet must satisfy one of the
  ;   ; rules defined here. A rule can be broken into two parts: matching & checking. A packet
  ;   ; will be matched against rules from the first to the last until a matched rule is
  ;   ; encountered. The matched rule will be used to check the packet. If a packet does not
  ;   ; match any rule, it will be treated as invalid.  The matching part of a rule consists
  ;   ; of `for` and `filter` sections. They collectively define which packets can be checked
  ;   ; with this rule. `for` defines packet type (data or interest) and `filter` defines
  ;   ; conditions on other properties of a packet. Right now, you can only define conditions
  ;   ; on packet name, and you can only specify ONLY ONE filter for packet name.  The
  ;   ; checking part of a rule consists of `checker`, which defines the conditions that a
  ;   ; VALID packet MUST have. See comments in checker section for more details.
  ;
  ;   rule
  ;   {
  ;     id "RIB Command Interest"
  ;     for interest
  ;     ; match Commmand Interest name
  ;     ; last three components are ControlParameters, timestamp, and random-value
  ;     ; SignatureInfo and SignatureValue are stripped before passing to the filter
  ;     filter
  ;     {
  ;       type name
  ;       regex ^<localhop><nfd><rib>[<register><unregister>]<>{3}$
  ;     }
  ;     checker
  ;     {
  ;       type customized
  ;       sig-type ecdsa-sha256
  ;       ; KeyLocator must be either a key name or a certificate name
  ;       key-locator
  ;       {
  ;         type name
  ;         regex ^<>*<KEY><>{1,3}$
  ;       }
  ;     }
  ;   }
  ;   rule
  ;   {
  ;     id "NDN Testbed Certificate Hierarchy"
  ;     for data
  ;     ; match certificate name only
  ;     filter
  ;     {
  ;       type name
  ;       regex ^<>*<KEY><>{3}$
  ;     }
  ;     checker
  ;     {
  ;       type customized
  ;       sig-type ecdsa-sha256
  ;       key-locator
  ;       {
  ;         type name
  ;         ; issuer subject name must be a prefix of issued certificate name
  ;         hyper-relation
  ;         {
  ;           k-regex ^(<>*)<KEY><>{1,3}$
  ;           k-expand \\1
  ;           h-relation is-prefix-of
  ;           p-regex ^(<>*)$
  ;           p-expand \\1
  ;         }
  ;       }
  ;     }
  ;   }
  ;   trust-anchor
  ;   {
  ;     type file
  ;     ; certificate path, relative to this config file
  ;     file-name keys/default.ndncert
  ;   }
  ;   ; trust-anchor entry may be repeated to specify multiple trust anchors
  ; }

  ; The following localhop_security should be enabled when NFD runs on a hub,
  ; which accepts all remote registrations and is a short-term solution.
  ; localhop_security
  ; {
  ;   trust-anchor
  ;   {
  ;     type any
  ;   }
  ; }

  ; The following prefix_announcement_validation accepts any prefix announcement
  prefix_announcement_validation
  {
    trust-anchor
    {
      type any
    }
  }

  auto_prefix_propagate
  {
    cost 15 ; forwarding cost of prefix registered on remote router
    timeout 10000 ; timeout (in milliseconds) of prefix registration command for propagation

    refresh_interval 300 ; interval (in seconds) before refreshing the propagation
    ; This setting should be less than face_system.udp.idle_time,
    ; so that the face is kept alive on the remote router.

    base_retry_wait 50 ; base wait time (in seconds) before retrying propagation
    max_retry_wait 3600 ; maximum wait time (in seconds) before retrying propagation
    ; for consequent retries, the wait time before each retry is calculated based on the back-off
    ; policy. Initially, the wait time is set to base_retry_wait, then it will be doubled for every
    ; retry unless beyond the max_retry_wait, in which case max_retry_wait is set as the wait time.
  }

  ; If enabled, routes registered with origin=client (typically from auto_prefix_propagate)
  ; will be readvertised into local NLSR daemon.
  readvertise_nlsr no
}