Skip to content

Basic Concepts

Jump to bottom
sat edited this page Sep 17, 2025 · 5 revisions

Basic Concepts

This page explains the fundamental concepts behind dot2net and the topology-driven configuration approach.

Topology-driven Configuration

The Problem with Traditional Network Configuration

Traditional network configuration management faces a critical challenge: tightly coupled topology and configuration. When you need to add a single device to a network, you typically must:

  1. Configure the new device with appropriate settings
  2. Update adjacent devices to recognize the new connection
  3. Calculate and assign IP addresses to avoid conflicts
  4. Modify routing configurations on related devices
  5. Ensure consistency across all affected configurations

This process is error-prone, time-consuming, and scales poorly as networks grow larger.

The Topology-driven Solution

Topology-driven configuration solves this by separating two distinct concerns:

Network Configuration = Topology Description + Generalized Configuration

1. Topology Description (What)

  • Network structure: Which devices exist and how they connect
  • Device roles: What type each device is (router, switch, host, etc.)
  • Connection properties: Link types, VLANs, protocol layers
  • Expressed in: DOT language (Graphviz format)

2. Generalized Configuration (How)

  • Device behavior: How each type of device should be configured
  • Template definitions: Reusable configuration patterns
  • Parameter policies: Automatic IP assignment, naming schemes
  • Expressed in: YAML configuration files

Key Benefits

With this separation, you can:

  • Change topology by modifying only the DOT file
  • Change device behavior by modifying only the YAML templates
  • Scale effortlessly as complexity is managed through reusable patterns
  • Eliminate errors through automatic parameter calculation and consistency

Core Architecture

Two-Level Object Model

dot2net uses a two-level object-oriented paradigm to represent network components:

Architecture Classes (AC)

  • Role-independent ownership structure
  • Examples: Network, Node, Interface, Connection, Group
  • Purpose: Form the hierarchical structure of the network
  • Relationship: Top-down ownership model

Configuration Classes (CC)

  • Role and behavior definitions
  • Examples: "router", "switch", "trunk_port", "access_vlan"
  • Purpose: Define how objects should be configured
  • Relationship: Bottom-up behavior model

Object Relationships

Object = Architecture Class + Configuration Class(es)
  • Each object belongs to exactly one AC
  • Each object can belong to multiple CCs
  • AC defines structure and ownership
  • CC defines configuration and behavior

Data Model Innovation

The Symmetry Requirement

Traditional config templates require complex control syntax (loops, conditionals) because data models lack parameter symmetry. dot2net solves this with:

Deterministic Templates

# Traditional approach (complex)
{% for interface in data.interfaces %}
interface {{ interface.id }}
 ip address {{ interface.ip }}/{{ interface.plen }}
{% endfor %}

# dot2net approach (simple)
interface {{ .name }}
 ip address {{ .ip_addr }}/{{ .ip_plen }}

Parameter Namespace Design

Each object has a symmetric parameter namespace containing:

  • Self parameters: Object's own properties
  • Relative parameters: Related objects' properties with consistent naming
  • Cross-object references: {{ .node_name }}, {{ .conn_vlan_id }}, etc.

Automatic Parameter Assignment

dot2net automatically calculates and assigns:

  • IP addresses based on topology and policies
  • Interface names following consistent patterns
  • Numeric identifiers (VLAN IDs, AS numbers, etc.)
  • Cross-references between related objects

Template System

Config Template Blocks

Instead of per-device templates, dot2net uses per-object template blocks:

  • Node templates: Generate per-device configuration
  • Interface templates: Generate per-interface configuration
  • Connection templates: Generate per-connection configuration
  • Group templates: Generate grouped/aggregated configuration

Template Processing

  1. Data Model Generation: Build object hierarchy and parameter namespaces
  2. Template Execution: Process each template block with its object's namespace
  3. Config Block Generation: Create configuration fragments
  4. File Assembly: Merge config blocks into final configuration files

Layer System

Protocol Layer Abstraction

dot2net supports multi-layer network descriptions without requiring separate input files:

  • Single topology graph with layer-aware labels
  • Automatic layer separation during processing
  • Examples: IPv4/IPv6 dual-stack, VXLAN overlays, BGP/OSPF multi-protocol

Layer Benefits

  • Simplified input: One DOT file instead of multiple layer-specific files
  • Consistent changes: Modify topology once, affects all relevant layers
  • Complex protocols: Support overlay networks, tunneling, multi-protocol routing

Object Categories

Substantial Objects

Objects that correspond directly to topology graph elements:

  • Network: The entire network
  • Node: Devices (routers, switches, hosts)
  • Interface: Device ports/interfaces
  • Connection: Links between devices
  • Group: Logical groupings (subnets, ASes, clusters)

Referential Objects

Objects generated automatically to avoid control syntax:

  • Neighbor: For iterating over adjacent interfaces
  • Member: For iterating over objects in the same class
  • Segment: For managing network segments and subnets

Practical Examples

Simple Topology Change

Before (Traditional):

1. Edit router1.conf (add interface, routing)
2. Edit router2.conf (add interface, routing)
3. Edit switch1.conf (add port configuration)
4. Calculate IP addresses manually
5. Update routing tables on 3+ devices
6. Test and debug configuration errors

After (dot2net):

1. Add one line to DOT file: router3 -> switch1
2. Run: dot2net build input.dot
3. Deploy generated configurations

Template Reusability

One interface template generates configuration for:

  • Hundreds of router interfaces
  • Different interface types (trunk, access, loopback)
  • Multiple protocols (IPv4, IPv6, MPLS)
  • Various network scenarios

The template automatically adapts based on:

  • Object's configuration classes
  • Calculated parameters (IP, VLAN, etc.)
  • Relationships to other objects

Design Principles

Declarative Description

  • Focus on "what" rather than "how"
  • Describe desired state rather than configuration steps
  • Let dot2net figure out the implementation details

Minimal Manual Input

  • Automatic parameter assignment wherever possible
  • Manual override capability when needed
  • Consistent naming and numbering schemes

Modular Extension

  • Plugin architecture for new protocols
  • Custom modules for specialized requirements
  • Standard interfaces for extending functionality

Understanding these concepts enables you to effectively use dot2net for both simple network scenarios and complex, large-scale emulation environments. The topology-driven approach scales from small test networks to enterprise-scale emulations with thousands of devices.

Clone this wiki locally