vyos

This MC creates a configuration for a VyOS router.

Model Component Dependencies:

Available Objects

exception vyos.IncorrectDefinitionOrderError[source]

Bases: Exception

Exception to specify that a value has been defined out of order. The message will specify what value was needed before the exception was thrown

class vyos.VyOSConfigItem(name, value=None)[source]

Bases: object

Single configuration item that represents either a block or a parameter in the vyos configuration file.

__init__(name, value=None)[source]

Constructor.

Parameters:

name (str) – The name of the block or parameter
value (str, optional) – Value for this block or parameter

add_children(*args)[source]

Add a child to this config item

Parameters:: *args (list) – A list of vyos.VyOSConfigItem objects.

find(child_name, value=None)[source]

Search the children of this node to find the specified configuration item.

Parameters:

child_name (str) – The name field for the desired config item
value (str, optional) – If specified then matches both the name and the item’s value.

Returns:

The child being searched for, or None if one is not found.

Return type:

vyos.VyOSConfigItem

generate_commands(base_command, commands)[source]

Generate the configuration commands for this item and all of its children. Then return commands back up to the parent to eventually be returned to the initial caller

Parameters:

base_command (str) – The base command for a given item.
commands (list) – The list of commands.

Returns:

The list of commands being generated.

Return type:

list

get_child_values(child_name)[source]

Search the children and get the values of all children that have the given name. Useful for getting all the interface names that have been declared since they are the values to ‘ethernet’ blocks.

Parameters:: child_name (str) – The name field for the desired config item
Returns:: A list of values.
Return type:: list

recursive_find(child_name, value=None)[source]

Recursively search the children of this node to find the specified configuration item.

Parameters:

child_name (str) – The name field for the desired config item
value (str, optional) – If specified then matches both the name and the item’s value.

Returns:

The child being searched for, or None if one is not found.

Return type:

vyos.VyOSConfigItem

class vyos.VyOSConfiguration[source]

Bases: object

Create configuration files for VyOS routers. Each OS may need minor differences in the command syntax, so this class and the methods within should be inherited extend functionality as needed.

__init__()[source]: Constructor. Creates a root node that can be stored in the graph

add_quality_of_service(iface)[source]

Adds quality of service blocks for all interfaces with QoS.

QoS traffic shapers are named according to the router interface. Currently, the bandwidth can be restricted to a maximum value, but the traffic shapers offer more advanced options, such as different types of queue scheduling.

Parameters:: iface (dict) – The interface to add QoS configs
Returns:: The VyOSConfigItem to add to the iface
Return type:: VyOSConfigItem

bgp_redistribute_ospf(redistribute, bgp_config=None)[source]

Create the ‘redistribution’ block that is nested inside of the ‘protocols’ block. Specifies which BGP links redistribute OSPF information.

Parameters:

redistribute (VyOSConfigItem) – The redistribute item or None if it does not exist.
bgp_config (dict) – Specifies which BGP links will be redistributing OSPF information. Structure defined in comments of set_router_ospf()

build_configuration_script()[source]

Generate the configuration script. This is called after all router attributes have been set. This traverses the tree to build the config and then returns the resulting configuration script

Returns:: The newly created configuration script.
Return type:: str

config = ''

create_bgp_neighbors(neighbor_info)[source]

Loop the BGP peer information and create config item objects for each.

Parameters:: neighbor_info (dict) – BGP peer information. Structure defined in comments in set_router_bgp()
Returns:: The list of all neighbors that were created.
Return type:: list

create_flow_accounting(router)[source]

Configures flow accounting for the router

Parameters:: router (dict) – The router to add flow accounting to

create_interfaces_ospf(ospf)[source]

Add OSPF information to the ‘interfaces’ block. This requires the creation of an ‘ip’ block as well as an ‘ospf’ block nested inside the ‘ip’ block.

See example in comments in set_router_interfaces()

Parameters:: ospf (dict) – OSPF information. Structure defined in comments of set_router_ospf()
Raises:: IncorrectDefinitionOrderError – Must set router interfaces before setting its OSPF information.

create_netflow(collector_ip, collector_port, engine_id)[source]

Configures netflow for the router

Parameters:

collector_ip (str) – The IP address of the collector
collector_port (str) – The port the collector runs on
engine_id (str) – The netflow engine ID

Returns:

The netflow configuration block.

Return type:

vyos.VyOSConfigItem

create_protocols_bgp_redistribute_ospf(bgp_config)[source]

Create the ‘redistribution’ block that is nested inside of the ‘protocols’ block. Specifies which BGP links redistribute OSPF information.

Parameters:

bgp_config (dict) – Specifies which BGP links will be redistributing OSPF information. Structure defined in comments of set_router_ospf()

Returns:

The “redistribute” configuration item that may need to be: added elsewhere.

Return type:

VyOSConfigItem

Raises:

IncorrectDefinitionOrderError – Must specify BGP information before specifying redistribution of OSPF on BGP links.

create_protocols_ospf(routing)[source]

Add OSPF information to the ‘protocols’ block.

Parameters:: routing (dict) – The routing info for this router.

create_protocols_ospf_area_networks(ospf)[source]

Groups OSPF information by area id with each network that is specified for that id.

Parameters:: ospf (dict) – OSPF information for each interface. Structure defined in comments of set_router_ospf()
Returns:: The OSPF area dictionary.
Return type:: dict
Raises:: IncorrectDefinitionOrderError – If the router interfaces were not set before adding OSPF information.

create_protocols_ospf_areas(ospf)[source]

Create the ‘area’ block that is nested inside the ‘ospf’ block which is nested inside the ‘protocols’ block. Specifies which area corresponds to which networks.

Parameters:: ospf (dict) – OSPF information for each interface. Structure defined in comments of set_router_ospf()
Returns:: A list of dictionaries containing a mapping of OSPF areas to networks.
Return type:: list

create_protocols_ospf_redistribute(ospf)[source]

Create the ‘redistribution’ block that is nested inside of the ‘protocols’ block. Specifies which OSPF links redistribute.

Parameters:: ospf (dict) – Specifies which OSPF links will be redistributing BGP information. Structure defined in comments of set_router_ospf()
Raises:: IncorrectDefinitionOrderError – Must specify OSPF information before specifying redistribution of BGP on OSPF links.

create_snmp_service()[source]

Creates the ‘snmp’ block nested in the ‘service’ block

Raises:: IncorrectDefinitionOrderError – Must set snmp service through the vyos.VyOSConfiguration.set_service() method.

create_ssh_service()[source]

Create ‘ssh’ block which is nested in the ‘service’ block

Raises:: IncorrectDefinitionOrderError – Must set ssh service through the vyos.VyOSConfiguration.set_service() method.

create_system_login()[source]

Creates the ‘login’ block which is nested inside the ‘system’ block

Raises:: IncorrectDefinitionOrderError – Must set system hostname before setting the system login.

get_configuration_root()[source]

Returns the root config item so that all the VyOSConfigItems can be stored in the graph.

Returns:: The root configuration item.
Return type:: vyos.VyOSConfigItem

root = None

set_dhcp_service(network_info)[source]

Creates the ‘dhcp-server’ block which is nested in the ‘service’ block.

Parameters:

network_info (dict) –

Dictionary describing DHCP parameters (IP, CIDR as string):

{
    <network name>: {
        'authoritative': <bool>
        <cidr>: {
            'gateway': <ip>,
            'dns1': <ip>,
            'dns2': <ip>,
            'domain': <string>,
            'lease': <int>,
            'range': (<ip>, <ip>),
            'static-mapping': {
                <hostname>: {
                    'ip': <ip>,
                    'mac': <mac>
                },
                ...
            }
        },
        ...
    },
    ...
}

set_firewall(rule_sets)[source]

Set the firewall parameters for this router

Parameters:: rule_sets (list) – A list containing firewall configurations (groups, rule sets, etc.) being applied to the router (each item in a configuration is a VyOSConfigItem object).

set_nat(nat)[source]

Set up the NAT rules for this router.

Parameters:: nat (list) – A list of NAT rules (in dictionary format).
Raises:: Exception – If there is an invalid NAT rule.

set_router_bgp(routing)[source]

Defines the BGP information for the router. This requires the neighbor_info structure which is defined as:

interface number (integer):

‘address’ (i.e. 192.168.1.4) ‘as’ (peer’s AS number, i.e. 1044)

The redistribute structure specifies information about which links will be redistributing OSPF information. The structure is defined as:

status – Enabled or Disabled, specifies if redistribution is active metric – the weight specified for the link route-map – route-map to be used when advertising the network

Parameters:: routing (dict) – The routing information for this router.
Raises:: Exception – Must specify an AS when defining a BGP block.

set_router_interfaces(ifaces, firewall_policies)[source]

Creates (if necessary) the router’s interfaces. Accomplishes this by creating the ‘interfaces’ block followed by the ‘ethernet’ block, which has several block nested in itself.

A sample ‘interfaces’ block looks like:

interfaces {
    ethernet eth0 {
        address 172.16.0.2/14
        duplex auto
        smp_affinity auto
    }
    ethernet eth1 {
        address 62.58.99.2/24
        duplex auto
        smp_affinity auto
        ip {
            ospf {
                dead-interval 40
                hello-interval 10
                retransmit-interval 5
                transmit-delay 1
            }
        }
    }
}

Parameters:

ifaces (dict) –

Double dictionary containing the interface information for the router. Structure is defined as:

interface number (int):
    'name'      (i.e. eth0)
    'address'   (i.e. 192.168.1.2)
    'netmask'   (i.e. 255.255.255.0)

firewall_policies (dict) – A mapping between the firewall policy category and associated rule set (each set is a VyOSConfigItem object).

# noqa: DAR101 firewall_policies # - required because newlines are required by RST but break # :spelling:ignore:`darglint` # (see https://github.com/terrencepreilly/darglint/issues/120)

set_router_ospf(routing)[source]

Defines OSPF information in the correct blocks in the vyos configuration. This is the main function for specifying all OSPF information for the router. The OSPF information comes in through the OSPF structure.

The OSPF structure is defined as:

interface number (integer):
    'name'                  (i.e. eth0)
    'status'                (i.e. Enabled)
    'area'                  (i.e. 0)
    'hello-interval'        (i.e. 10)
    'transmit-delay'        (i.e. 1)
    'retransmit-interval'   (i.e. 5)
    'dead-interval'         (i.e. 40)

The redistribute structure specifies which links will be redistributing BGP information over the OSPF link.

The redistribute structure is defined as:

status – Enabled or Disabled, specifies if redistribution is active

metric – the weight specified for the link

metric-type – specifies how cost is calculated for the link

route-map – route-map to be used when advertising the network

Parameters:: routing (dict) – The routing information for this router.

set_router_static(routing)[source]

Defines static routing information

Parameters:: routing (dict) – The routing information for this router

set_service()[source]

Creates (if necessary) the ‘service’ block of the vyos configuration file. This is the main function for creating this block.

A sample ‘service’ block looks like:

service {
   ssh {
       allow-root
       port 22
       protocol-version v2
   }
   snmp {
       community public
   }
}

set_system(hostname)[source]

Creates (if necessary) and sets the ‘system’ block in the configuration file.

This is the main function for creating the ‘system’ block. A sample ‘system’ block looks like:

system {
    host-name subnet-0-amsterdam-Rtr-0
    login {
        user vyos {
            authentication {
                plaintext-password vyos
            }
            level admin
        }
    }
}

Parameters:: hostname (str) – The name of the router

class vyos.VyOSRouter(*args, **kwargs)[source]

Bases: object

This object provides some generic functionality that is common to all versions of VyOS virtual router operating system If the router isn’t already a GenericRouter this will fail on __init__ arguments missing.

__init__(*args, **kwargs)

_configure_dhcp()[source]: Determine if and where we need to run a DHCP server and find the necessary info to do so in the graph. Build the configuration entries for this.

_configure_dhcp_mappings(switch, host_to_ignore)[source]

Build a list of static mappings for IP addresses based on hosts connected to the network.

Parameters:

switch (base_objects.Switch) – Switch for the network for which we are building the list.
host_to_ignore (str) – A name of a host for which we should ignore mapping.

Returns:

A dictionary in the correct format for the ‘static-mapping’ field of a DHCP configuration.

Return type:

dict

Raises:

RuntimeError – The given switch was not decorated as a base_objects.Switch.

_configure_vyos()[source]

Configure VyOS by setting interfaces, OSPF, BGP, DHCP, etc.

Returns:: The configuration script as a string.
Return type:: str
Raises:: RuntimeError – If the self.vyos_config_class is not an instance of vyos.VyOSConfiguration.

_resolve_nat()[source]: Resolve a NAT block so all specifications use the detailed syntax and interfaces refer to names, not nat-labels. This is needed for the configuration generation to function properly.

_resolve_nat_interfaces()[source]

Resolve a NAT block so all interface references use name, not nat-label. Assumes all rules are already use detailed syntax.

Raises:: ValueError – If there is an invalid NAT rule.

_resolve_nat_simplified_syntax()[source]

Resolve a NAT block so all rules use the detailed syntax.

Raises:: ValueError – If there is an invalid NAT rule.

static _validate_firewall_policies(policies)[source]

add_default_profiles()[source]: Adds default ssh keys, .bashrc, .vimrc, etc. to both the root and vyos user.

assign_firewall_policies(policies)[source]

Assign firewall policies/rules to the router.

Parameters:: policies (dict) – A mapping between policy categories and a list containing rule sets and/or groups that apply to the policy category. Keys be a subset of {"in", "out", "local"} and values must be a list of VyOSConfigItem objects.