Tutorial

Tutorial

This tutorial will guide you through installing dot2net and creating your first network topology.

What is dot2net?

dot2net implements Topology-driven Configuration, a revolutionary approach that separates network topology from generalized configuration settings. Instead of manually editing multiple device configurations when adding a single router, dot2net generates all required configuration files from a simple topology graph (DOT) and reusable configuration templates (YAML).

How dot2net Works

dot2net transforms network topology into emulation-ready configurations through a 4-step process:

1. Convert: Parse DOT topology into network model with object instances
2. Assign parameters: Automatically calculate IP addresses, interface names, and other parameters
3. Embed variables: Process templates with assigned parameters to generate config blocks
4. Merge and format: Combine config blocks into final configuration files and deployment specifications

This separation enables topology-driven configuration where changing the network layout only requires modifying the DOT file, while all device configurations are automatically regenerated.

---

Prerequisites

For building dot2net:

• Go 1.23+ OR Docker

For deploying generated networks:

• Using Containerlab/TiNET: Linux environment with Docker and sudo privilege
• Manual deployment: Any environment (dot2net generates config files only)

Deployment platforms (choose one):

• Containerlab - container-based network labs
• TiNET - Linux namespace-based emulation
• Manual deployment to physical/virtual equipment

---

Installation

Option 1: Build with Go

# Clone the repository
git clone https://github.com/cpflat/dot2net.git
cd dot2net

# Build
go build .

Option 2: Build with Docker

# Clone the repository
git clone https://github.com/cpflat/dot2net.git
cd dot2net

# Build using Docker
docker run --rm -i -v $PWD:/v -w /v golang:1.23.4 go build -buildvcs=false

After building, you'll have a dot2net executable in your current directory.

---

Your First Network

Let's create a simple 3-router network to understand the basics.

Step 1: Navigate to Tutorial Scenario

cd tutorial/

This directory contains a pre-configured example with:

• input.dot - Network topology
• input.yaml - Configuration templates

Step 2: Review the Topology

View input.dot:

digraph {
    r1 [xlabel="router"];
    r2 [xlabel="router"];
    r3 [xlabel="router"];

    r1 -> r2 [dir="none"];
    r2 -> r3 [dir="none"];
}

This defines:

• Three routers (r1, r2, r3) with class label "router"
• Two bidirectional connections: r1↔r2 and r2↔r3

Step 3: Generate Configuration Files

../dot2net build -c ./input.yaml ./input.dot

This command:

• Reads the topology from input.dot
• Applies configuration from input.yaml
• Generates output files:
  • r1/, r2/, r3/ - Node-specific configuration directories
  • topo.yaml - Containerlab deployment specification
  • spec.yaml - TiNET deployment specification

Step 4: Deploy the Network

Choose one deployment method:

Option A: Deploy with Containerlab

# Deploy
sudo containerlab deploy --topo topo.yaml

# Test connectivity
docker exec -it clab-tutorial-r1 ping <r3_ip>

# Cleanup
sudo containerlab destroy --topo topo.yaml

Option B: Deploy with TiNET

# Create network namespace and interfaces
tinet up -c spec.yaml | sudo sh -x

# Apply configurations
tinet conf -c spec.yaml | sudo sh -x

# Test connectivity (from host)
sudo ip netns exec r1 ping <r3_ip>

# Cleanup
tinet down -c spec.yaml | sudo sh -x

---

Understanding dot2net Files

Input Files

input.dot - Network Topology

Defines the network structure using DOT language (Graphviz format):

• Nodes: Network devices (routers, switches, hosts)
• Edges: Connections between devices
• Labels: Class assignments for configuration

Key syntax:

digraph {
    node_name [xlabel="class_label"];
    node1 -> node2 [dir="none"];  # Bidirectional connection
}

Learn more: DOT File Syntax

input.yaml - Configuration Templates

Defines configuration behavior using YAML:

• Classes: Reusable configuration patterns (NodeClass, InterfaceClass, ConnectionClass)
• Templates: Go template files for generating device configs
• IP Policies: Address assignment rules

Key sections:

classes:
  node:
    router:
      # Router configuration

  interface:
    default:
      # Interface configuration

files:
  - format: ...
    template: ...

Learn more: YAML Configuration

Generated Files

After running dot2net build, you'll see:

• r1/, r2/, r3/: Node-specific configuration directories
  • Contains device configs (e.g., FRR daemons, frr.conf)
• topo.yaml: Containerlab deployment specification
• spec.yaml: TiNET deployment specification

---

Key Features

dot2net provides powerful features for network configuration management:

• Automatic Parameter Assignment: IP addresses, interface names, and other parameters are calculated automatically
• Flexible Class System: Reusable node, interface, connection, and group configurations
• Template-Based Configuration: Generate any configuration format using Go templates
• Multi-Platform Support: TiNET and Containerlab emulation platforms
• Conflict Detection: Intelligent detection and reporting of configuration conflicts
• Scalable Design: Handle large networks with hundreds of nodes and connections

---

Supported Platforms

dot2net generates configurations for multiple deployment platforms:

• TiNET: Linux namespace-based network emulation
• Containerlab: Container-based network labs
• Manual deployment: Use generated configs for physical or virtual equipment

---

Next Steps

Now that you've created your first network, explore these topics:

1. Basic Concepts - Understanding topology-driven configuration
2. DOT File Syntax - Learn advanced topology definitions
3. YAML Configuration - Master the class system and templates
4. Best Practices - Design principles for scalable networks
5. Template System - Create custom configuration templates

---

Troubleshooting

Build errors

Problem: go build fails with dependency errors Solution: Ensure you're using Go 1.23+ and run go mod download

Problem: Docker build fails Solution: Check Docker is running and you have network connectivity

Deployment errors

Problem: Containerlab fails with permission error Solution: Ensure you're using sudo when running containerlab deploy

Problem: TiNET commands fail Solution: TiNET requires Linux with network namespace support. Check you're on a Linux system with proper kernel support.

Configuration errors

Problem: dot2net build fails with parsing errors Solution: Validate your DOT syntax using dot -Tpdf input.dot -o test.pdf to check for syntax errors

Problem: IP address conflicts Solution: Review your YAML configuration's address assignment policies

For more help, visit the GitHub Issues page.