vyos package

Submodules

vyos.base module

exception vyos.base.ConfigError

Bases: builtins.Exception

vyos.config module

A library for reading VyOS running config data.

This library is used internally by all config scripts of VyOS, but its API should be considered stable and it is safe to use in user scripts.

Note that this module will not work outside VyOS.

Node taxonomy

There are multiple types of config tree nodes in VyOS, each requires its own set of operations.

Leaf nodes (such as “address” in interfaces) can have values, but cannot have children. Leaf nodes can have one value, multiple values, or no values at all.

For example, “system host-name” is a single-value leaf node, “system name-server” is a multi-value leaf node (commonly abbreviated “multi node”), and “system ip disable-forwarding” is a valueless leaf node.

Non-leaf nodes cannot have values, but they can have child nodes. They are divided into two classes depending on whether the names of their children are fixed or not. For example, under “system”, the names of all valid child nodes are predefined (“login”, “name-server” etc.).

To the contrary, children of the “system task-scheduler task” node can have arbitrary names. Such nodes are called tag nodes. This terminology is confusing but we keep using it for lack of a better word. The knowledge of whether in “task Foo” the “tag” is “task” or “Foo” is lost in time, luckily, the distinction is irrelevant in practice.

Configuration modes

VyOS has two distinct modes: operational mode and configuration mode. When a user logins, the CLI is in the operational mode. In this mode, only the running (effective) config is accessible for reading.

When a user enters the “configure” command, a configuration session is setup. Every config session has its proposed config built on top of the current running config. When changes are commited, if commit succeeds, the proposed config is merged into the running config.

For this reason, this library has two sets of functions. The base versions, such as exists or return_value are only usable in configuration mode. They take all nodes into account, in both proposed and running configs. Configuration scripts require access to uncommited changes for obvious reasons. Configuration mode completion helpers should also use these functions because not having nodes you’ve just created in completion is annoying.

However, in operational mode, only the running config is available. Currently, you need to use special functions for reading it from operational mode scripts, they can be distinguished by the word “effective” in their names. In the future base versions may be made to detect if they are called from a config session or not.

class vyos.config.Config

Bases: builtins.object

The class of config access objects.

Internally, in the current implementation, this object is almost stateless, the only state it keeps is relative config path for convenient access to config subtrees.

exists(path)

Checks if a node with given path exists in the running or proposed config

Returns:
True if node exists, False otherwise
Note:
This function cannot be used outside a configuration sessions. In operational mode scripts, use exists_effective.
exists_effective(path)

Check if a node exists in the running (effective) config

Args:
path (str): Configuration tree path
Returns:
True if node exists in the running config, False otherwise
Note:
This function is safe to use in operational mode. In configuration mode, it ignores uncommited changes.
get_level()

Gets the current edit level.

Returns:
str: current edit level
in_session()
Returns:
True if called from a configuration session, False otherwise.
is_leaf(path)
Args:
path (str): Configuration tree path
Returns:
True if a node is a leaf node, False otherwise.
Note:
It also returns False if node doesn’t exist.
is_multi(path)
Args:
path (str): Configuration tree path
Returns:
True if a node can have multiple values, False otherwise.
Note:
It also returns False if node doesn’t exist.
is_tag(path)
Args:
path (str): Configuration tree path
Returns:
True if a node is a tag node, False otherwise.
Note:
It also returns False if node doesn’t exist.
list_effective_nodes(path, default=[])

Retrieve names of all children of a tag node in the running config

Args:
path (str): Configuration tree path
Returns:
str list: child node names
Raises:
VyOSError: if the node is not a tag node
Note:
There is no way to list all children of a non-tag node in the current config backend.
list_nodes(path, default=[])

Retrieve names of all children of a tag node in the running or proposed config

Args:
path (str): Configuration tree path
Returns:
string list: child node names
Raises:
VyOSError: if the node is not a tag node
Note:

There is no way to list all children of a non-tag node in the current config backend.

This function cannot be used outside a configuration session. In operational mode scripts, use list_effective_nodes.

return_effective_value(path, default=None)

Retrieve a values of a single-value leaf node in a running (effective) config

Args:
path (str): Configuration tree path default (str): Default value to return if node does not exist
Returns:
str: Node value
Raises:
VyOSError: if node is not a multi-value leaf node
return_effective_values(path, default=[])

Retrieve all values of a multi-value node in a running (effective) config

Args:
path (str): Configuration tree path
Returns:
str list: A list of values
Raises:
VyOSError: if node is not a multi-value leaf node
return_value(path, default=None)

Retrieve a value of single-value leaf node in the running or proposed config

Args:
path (str): Configuration tree path default (str): Default value to return if node does not exist
Returns:
str: Node value, if it has any None: if node is valueless or if it doesn’t exist
Raises:
VyOSError: if node is not a single-value leaf node
Note:

Due to the issue with treatment of valueless nodes by this function, valueless nodes should be checked with exists instead.

This function cannot be used outside a configuration session. In operational mode scripts, use return_effective_value.

return_values(path, default=[])

Retrieve all values of a multi-value leaf node in the running or proposed config

Args:
path (str): Configuration tree path
Returns:
str list: Node values, if it has any None: if node does not exist
Raises:
VyOSError: if node is not a multi-value leaf node
Note:
This function cannot be used outside a configuration session. In operational mode scripts, use return_effective_values.
session_changed()
Returns:
True if the config session has uncommited changes, False otherwise.
set_level(path)

Set the edit level, that is, a relative config tree path. Once set, all operations will be relative to this path, for example, after set_level("system"), calling exists("name-server") is equivalent to calling exists("system name-server" without set_level.

Args:
path (str): relative config path
exception vyos.config.VyOSError

Bases: builtins.Exception

Raised on config access errors, most commonly if the type of a config tree node in the system does not match the type of operation.

vyos.configtree module

class vyos.configtree.ConfigTree(config_string, libpath='/usr/lib/libvyosconfig.so.0')

Bases: builtins.object

delete(path)
delete_value(path, value)
exists(path)
is_tag(path)
list_nodes(path)
return_value(path)
return_values(path)
set(path, value=None, replace=True)
set_tag(path)
to_commands()
to_string()
exception vyos.configtree.ConfigTreeError

Bases: builtins.Exception

vyos.configtree.check_path(path)
vyos.configtree.strip_comments(s)

Split a config string into the config section and the trailing comments

vyos.defaults module

vyos.interfaces module

vyos.interfaces.list_interfaces()
vyos.interfaces.list_interfaces_of_type(typ)

vyos.limericks module

vyos.limericks.get_random()

vyos.util module

vyos.util.colon_separated_to_dict(data_string, uniquekeys=False)
Converts a string containing newline-separated entries

of colon-separated key-value pairs into a dict.

Such files are common in Linux /proc filesystem

Args:
data_string (str): data string uniquekeys (bool): whether to insist that keys are unique or not

Returns: dict

Raises:
ValueError: if uniquekeys=True and the data string has
duplicate keys.
Note:
If uniquekeys=True, then dict entries are always strings, otherwise they are always lists of strings.

vyos.version module

vyos.version.get_version(file=None)
vyos.version.get_version_data(file='/usr/share/vyos/version.json')

Module contents