netconfd(1)

📦
version 2.14 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ netconfd ✨ 💅

okay bestie, buckle up. you're looking at netconfd(1) — the manual page for netconfd version 2.14. it's giving "serious server energy" and honestly? it ate. let's go. 🫶

🌸 NAME 🌸

netconfd — a YANG-based NETCONF-over-SSH server. that's the whole personality. it does NETCONF, it rides over SSH, it's YANG-based. iconic behavior only. 👑

🎀 SYNOPSIS 🎀

netconfd [parameter=value...]

netconfd --help [brief | normal | full]

netconfd --version

🦋 DESCRIPTION 🦋

so netconfd is a YANG-based NETCONF server, and the way you use it is with an SSH server — like OpenSSH, for example. they're a duo. a collab. 🤝

this version of netconfd supports the YANG data modeling language as defined in RFC 6020. yes, an actual RFC. we're being official today. 💅

🌈 USAGE 🌈

parameters can go in any order you want, bestie, and they look like this:

[start] name [separator [value]]

where:

  • start == 0, 1, or 2 dashes (foo, -foo, --foo)
  • name == parameter name
    • Parameter name completion will be attempted if a partial name is entered.
  • separator == whitespace or equals sign (foo=bar, foo bar)
  • value == string value for the parameter.
    • Strings with whitespace need to be double quoted (--foo="some string")

some examples of valid command line parameters, because seeing it hits different:

foo=3
-foo=3
--foo=3
foo 3
foo=fred
--foo "fred flintstone"

and the lil cherry on top: partial parameter names can be entered if they are unique. type less, get more. we love efficiency. ✨

💖 OPTIONS 💖

okay this is the big one. every single option, no skips, no cuts. let's get into it. 🍓

  • --access-control=enum — controls how the ietf-netconf-acm access control model will be enforced while the server is running. pick your fighter:
    • enforcing: All configured access control rules will be enforced.
    • permissive: All configured access control rules will be enforced for write and execute requests. All read requests will be allowed, unless the requested object contains the nacm:very-secure extension. In that case, all configured access control rules will be enforced.
    • disabled: All read, write, and execute requests will be allowed, unless the object contains the nacm:secure or nacm:very-secure extension. If the nacm:secure extension is in effect, then all configured access control rules will be enforced for write and execute requests. If the nacm:very-secure extension is in effect, then all configured access control rules will be enforced for all requests.
bestie. use this mode with caution. fr fr.
  • off: All access control enforcement is disabled.
use this mode with extreme caution. i am not joking around. 💀
  • --audit-log=filespec — the filespec for the server audit log file, which gets used in addition to the normal log file or STDOUT. two logs, two vibes.
  • --audit-log-append — if it's present, the audit log gets appended, not over-written. if it's not present, the audit log gets over-written. only meaningful if the audit-log parameter is also present. they're a package deal. 🫶
  • --config=filespec — the name of the configuration file to use. any parameter except this one can be set in the config file. and heads up: the default config file /etc/yuma/netconfd.conf will not be checked if this parameter is present. she's exclusive. 💅
  • --datapath=list — internal file search path for configuration data files. this overrides the YUMA_DATAPATH environment variable. also, this parameter affects the search for the startup configuration file (default: startup-cfg.xml).
  • --default-style=enum — picks the type of filtering behavior the server will advertise as the 'basic' behavior in the 'with-defaults' capability. the server uses this default handling behavior if the 'with-defaults' parameter is not explicitly set.

also, when saving a configuration to NV-storage, this value is what gets used for filtering defaults out of the saved configuration. multi-tasking queen. 👑

  • report-all: report all values
  • trim: remove leafs containing the YANG default value
  • explicit: report only the nodes that have been created by the client or the server. This is the default value.
  • --delete-empty-npcontainers=boolean — selects whether the server keeps or deletes empty non-presence containers in the running and startup configurations. set to true to delete these containers, and false to keep them. default: false.
🚨 this parameter is deprecated! it is ignored by the server! it's giving ghost of options past. 🙈
  • --deviation=string — this parameter identifies a YANG module that should only be checked for deviation statements for external modules. those get collected and applied to the real module(s) being processed.

deviations are applied as patches to the target module. since they are not identified in the target module at all (ala imports), they have to be specified explicitly, so they will be correctly processed. zero or more instances of this parameter are allowed. stack 'em. 🧚

  • --eventlog-size=number — the maximum number of notification events that will be saved in the notification replay buffer. the oldest entries get deleted first (first in, first out, classic). the default value is 1000.
  • --feature-disable=module:feature — identifies a feature which should be considered disabled. zero or more entries are allowed.
  • --feature-enable-default=boolean — if true (which is the default), then features will be enabled by default. if false, then features will be disabled by default. the toggle of toggles.
  • --feature-enable=module:feature — identifies a feature which should be considered enabled. zero or more entries are allowed. twin of --feature-disable, but make it positive. ✨
  • --hello-timeout=number — the number of seconds that a session may exist before the hello PDU is received. a session gets dropped if no hello PDU shows up before this number of seconds elapses. no hello, no entry. 😤

if this parameter is set to zero, then the server will wait forever for a hello message, and will not drop any sessions stuck in 'hello-wait' state.

setting this parameter to zero may permit denial of service attacks, since only a limited number of concurrent sessions are supported by the server. bestie, be careful. 😭

(range 0 | 10 .. 3600). the default value is 600 seconds (10 minutes).

  • --help — print this help text and exit. the help-mode choice (--brief, --normal, or --full) may also be present to control the amount of help text printed. lil menu of menus. 🎀
  • --home=dirspec — directory specification for the home directory to use instead of HOME.
  • --idle-timeout=number — the number of seconds that a session may remain idle without issuing any RPC requests. a session gets dropped if it is idle for an interval longer than this number of seconds.

plot twist though: sessions that have a notification subscription active are never dropped. subscription girlies stay winning. 💅

if this parameter is set to zero, then the server will never drop a session because it is idle. (range 0 | 10 .. 360000). the default value is 3600 seconds (1 hour).

  • --indent=number — number of spaces to indent (0..9) in formatted output. the default is 2 spaces. neat freak behavior, and honestly? valid.
  • --log=filespec — filespec for the log file to use instead of STDOUT. if this string begins with a '~' character, then a username is expected to follow or a directory separator character. if it begins with a '$' character, then an environment variable name is expected to follow. she reads your shortcuts. 🔥
  • --log-append — if present, the log gets appended, not over-written. if not, the log gets over-written. only meaningful if the log parameter is also present.
  • --log-level=enum — sets the debug logging level for the program. turn the dial up or down.
  • --max-burst=number — the maximum number of notifications that should be sent to one session, within a one second time interval. the value 0 means the server should not limit notification bursts at all. the default value is 10. pace yourself bestie, it's a marathon not a sprint. 🦋
  • --modpath=list — directory search path for YANG and YIN files. this overrides the YUMA_MODPATH environment variable.
  • --module=string — YANG or YIN source module name to load at startup. the server will attempt to load the specified module and its corresponding server instrumentation library (SIL).

if this string represents a filespec, ending with the .yang or .yin extension, then only that file location will be checked.

if this string represents a module name, then the module search path will be checked for a file the .yang or .yin extension.

if this string begins with a '~' character, then a username is expected to follow or a directory separator character. if it begins with a '$' character, then an environment variable name is expected to follow.

~/some/path ==> <my-home-dir>/some/path

~fred/some/path ==> <fred-home-dir>/some/path

$workdir/some/path ==> <workdir-env-var>/some/path

look at those little arrows doing their thing. obsessed. ✨

  • --ncxserver-sockname=path — overrides the default /tmp/ncxserver.sock UNIX socket name that netconfd listens on for incoming connections. you have to add a corresponding entry to /etc/ssh/sshd_config, e.g.:
...
Port 1830
Subsystem netconf
...
  • --port=number — specifies the TCP ports that the server will accept connections from. these ports must also be configured in the /etc/ssh/sshd_config file for the SSH master server to accept the connection and invoke the netconf subsystem.

up to 4 port numbers can be configured.

if any ports are configured, then only those values will be accepted by the server.

if no ports are configured, then the server will accept connections on the netconf-ssh port (tcp/830).

  • --protocols=bits — specifies which NETCONF protocol versions the server will attempt to use. the empty set is not allowed (empty set, you are not invited 💀). the values 'netconf1.0' and 'netconf1.1' are supported. the default is to enable both NETCONF protocol versions. both, because why choose. 🫶
  • --runpath=pathlist — internal file search path for executable modules. this overrides the YUMA_RUNPATH environment variable.
  • --running-error=enum — if 'stop', then errors in the running configuration will be treated as fatal errors. if 'continue', the server will attempt to continue if any validataion errors are found in the running configuration at startup. the default is 'stop'.

and bestie... that's genuinely not even the whole list. we are so not done here. keep scrolling, part 2 is coming and it's gonna be just as good. 🌈💜

  • --startup=filespec — bestie, this is where you point at the full or relative filespec of the startup config file you wanna use. If you pass it, it overrides the default startup config file name 'startup-cfg.xml'. It'll also override the YUMA_DATAPATH environment variable and the datapath CLI parameter — but only if the first character is the forward slash /, meaning absolute file path. 🫶 And heads up: if this parameter is present, then --no-startup and --factory-startup cannot be present. Fun fact: this is the default, which will cause startup-cfg.xml to be used if not present. ✨
  • --no-startup — if present, do not load the startup config file, bestie. Use only factory default values instead. It does not affect the startup.cfg file, if present. If this parameter is present, then the --startup or --factory-startup parameter cannot be present. 💅
  • --factory-startup — force the system to use the factory configuration and delete the startup config file if it exists. Also forces the NV-storage startup to contain the factory default configuration. If this parameter is present, then the --no-startup and --startup parameters cannot be present. It's giving factory reset energy 😭
  • --startup-error=enum — if 'stop', then any errors in the startup configuration get treated as fatal errors. If 'continue', the server will attempt to continue if any errors are found in the database loaded from NV-storage to running at boot-time. The default is 'stop'. No cap.
  • --subdirs=boolean — if false, the file search paths for modules, scripts, and data files will not include sub-directories if they exist in the specified path.

If true, then those file search paths will include sub-directories, if present. Any directory name beginning with a dot (.) character, or named CVS, will be ignored. This is the default mode. 🎀

  • --superuser=string — the user name to use as the superuser account. Any session associated with this user name will bypass all access control enforcement. See ietf-netconf-acm.yang for more details. There is no default value. 👑
  • --system-sorted=boolean — tells you whether ordered-by system leaf-lists and lists will be kept in sorted order. The default is true. ⭐
  • --target=enum — specifies the database to use as the target of edit-config operations.

Enum values:

  • running — write to the running config and support the :writable-running capability.
  • candidate — write to the candidate config and support the :candidate and :confirmed-commit capabilities.
  • --usexmlorder — if present, then XML element order will be enforced. Otherwise, XML element order errors will not be generated if possible. Default is no enforcement of strict XML order. 🦋
  • --version — print the program version string and exit. That's it, that's the whole vibe. ✨
  • --validate-config-only — if present, netconfd acts as a command line YANG configuration validator. It loads the YANG schema modules, validates the startup configuration, and exits without opening a socket and listening for incoming sessions. Very demure, very mindful. 🧚
  • --warn-idlen=number — controls whether identifier length warnings will be generated. The value zero disables all identifier length checking. If non-zero, then a warning gets generated if an identifier is defined which has a length greater than this amount. range: 0 | 8 .. 1023. The default value is 64. 💜
  • --warn-linelen=number — controls whether line length warnings will be generated. The value zero disables all line length checking. If non-zero, then a warning gets generated if the line length is greater than this amount. Tab characters are counted as 8 spaces. range: 0 | 40 .. 4095. The default value is 72. 🌸
  • --warn-off=number — controls whether the specified warning number will be generated and counted in the warning total for the module being parsed. range: 400 .. 899. This parameter may be entered zero or more times. 🙈
  • --with-startup=boolean — if set to 'true', then the :startup capability will be enabled. Otherwise, the :startup capability will not be enabled. This capability makes the NV-save operation an explicit operation instead of an automatic save. The default value is false. 🔥
  • --with-url=boolean — if set to 'false', then the :url capability will be disabled. Otherwise, the :url capability will be enabled. This capability allows local files to be stored as backups on the server. The default value is true. 🌈
  • --with-validate=boolean — if set to 'true', then the :validate capability will be enabled. Otherwise, the :validate capability will not be enabled. Heads up bestie, this capability requires extensive memory resources. The default value is true. 💀
  • --yuma-home=string — the directory for the yuma project root to use. If present, this directory location will override the YUMA_HOME environment variable, if it is present. If a zero-length string is entered, then the YUMA_HOME environment variable will be ignored. 🍓

📥 INPUT FILES

YANG modules can be loaded at startup with the --module command, or loaded at run-time with the load operation. Both slay, pick your fighter. 💖

🔍 SEARCH PATH

When a module name is entered as input, or when a module or submodule name is specified in an import or include statement within the file, the following search algorithm is used to find the file:

  1. file is in the current directory
  2. YUMA_MODPATH environment var (or set by modpath parameter)
  3. $HOME/modules directory
  4. $YUMA_HOME/modules directory
  5. $YUMA_INSTALL/modules directory OR default install module location, '/usr/share/yuma/modules'

By default, the entire directory tree for all locations (except step 1) will be searched, not just the specified directory. The subdirs parameter can be used to prevent sub-directories from being searched. 🫶

Any directory name beginning with a dot character (.) will be skipped. Also, any directory named CVS will be skipped in directory searches. Not invited to the party, sorry not sorry. ✨

📝 ERROR LOGGING

By default, warnings and errors are sent to STDOUT. 👀

A log file can be specified instead with the log parameter.

Existing log files can be reused with the logappend parameter, otherwise log files are overwritten. 😭

The logging level can be controlled with the log-level parameter.

The default log level is 'info'. The log-levels are additive:

off:    suppress all errors (not recommended!)
        A program return code of '1' indicates some error.
error:  print errors
warn:   print warnings
info:   print generally interesting trace info
debug:  print general debugging trace info
debug2: print verbose debugging trace info
debug3: print very verbose debugging trace info
debug4: print maximum debugging trace info
Not recommended on off, bestie — suppressing all errors is a choice, and it's a scary one. 💀

🌍 ENVIRONMENT

The following optional environment variables can be used to control module search behavior:

  • HOME — the user's home directory (e.g., /home/andy) 🏠
  • YUMA_HOME — the root of the user's Yuma work directory (e.g., /home/andy/swdev/netconf)
  • YUMA_INSTALL — the root of the directory that yangdump is installed on this system (default is, /usr/share/yuma)
  • YUMA_DATAPATH — colon-separated list of directories to search for data files. (e.g.: './workdir/data-files:/home/andy/data') The datapath parameter will override this environment variable, if both are present.
  • YUMA_MODPATH — colon-separated list of directories to search for modules and submodules. (e.g.: './workdir/modules:/home/andy/test-modules') The modpath parameter will override this environment variable, if both are present.

⚙️ CONFIGURATION FILES

  • netconfd.conf — YANG config file. The default is: /etc/yuma/netconfd.conf

An ASCII configuration file format is supported to store command line parameters.

The config parameter is used to specify a specific config file, otherwise the default config file will be checked.

  • A hash mark until EOLN is treated as a comment
  • All text is case-sensitive
  • Whitespace within a line is not significant
  • Whitespace to end a line is significant. Unless the line starts a multi-line string, an escaped EOLN (backslash EOLN) is needed to enter a leaf on multiple lines.
  • For parameters that define lists, the key components are listed just after the parameter name, without any name, e.g.,
interface eth0 {
  # name = eth0 is not listed inside the braces
  ifMtu 1500
  ifName mySystem
}

A config file can contain any number of parameter sets for different programs.

Each program must have its own section, identified by its name:

# this is a comment
yangdump {
   log-level debug
   output "~/swdev/testfiles"
}

netconfd {
   ...
}

📂 FILES

The following data files must be present in the module search path in order for this program to function:

  • YANG module library — default: /usr/share/yuma/modules/

🩺 DIAGNOSTICS

Internal diagnostics may generate the following type of message if any bugs are detected at runtime:

[E0]
     filename.c:linenum error-number (error-msg)

👑 AUTHORS

Andy Bierman, <andy at netconfcentral dot org>

Vladimir Vassilev, <vladimir at lightside-instruments dot com>

🔗 SEE ALSO

netconf-subsystem(1) pyang(1) yangcli(1)

And that's a wrap, bestie!! 🎀 This little legend lives in the Linux world, dated March 23, 2025, and it's the netconfd(1) manual page — go forth and configure responsibly, ily, mwah 💖✨

📦 where this page comes from