Skip to content

Parameter Generation

Jump to bottom
sat edited this page Jan 3, 2026 · 1 revision

Parameter Generation

This page explains how dot2net automatically generates and assigns parameters to network objects.

Overview

dot2net automatically generates various parameters to ensure consistent and error-free network configurations:

  1. Built-in Parameters: Object naming, IP addresses, interface names
  2. User-defined Parameters: Custom parameters via param_rule

Built-in Parameter Generation

Object Naming

Each object automatically receives a name parameter:

Object Type Naming Source
Node DOT node ID
Interface Auto-generated (e.g., eth0, eth1)
Connection Auto-generated from connected nodes
Group DOT subgraph ID

IP Address Assignment

IP addresses are automatically assigned per layer in a two-stage process:

Stage 1: Network Segment Assignment

First, dot2net identifies network segments by traversing connections:

  • Interfaces that are layer-aware (have IP policy) form segment boundaries
  • All interfaces in a segment share the same network prefix

Then, network prefixes are assigned to segments from the IP policy pool:

layer:
  - name: ip
    ip_policy:
      - name: default
        range: 192.168.0.0/16
        prefix: 24           # Each segment gets a /24 block

Stage 2: IP Address Assignment

Within each segment, individual IP addresses are assigned to interfaces:

  • Addresses are allocated sequentially from the segment's prefix
  • Network address and broadcast address are skipped (IPv4)

ValueLabel Reservation

When IP addresses or networks are specified via ValueLabel in DOT:

r1 -- r2 [ip="192.168.100.0/24"]     // Reserve network for this segment
r1 [net0:ip="192.168.100.1"]          // Reserve specific IP for interface
  • Network reservation: The segment uses the specified prefix instead of auto-allocation
  • Address reservation: The specified address is reserved; other interfaces in the segment avoid it
  • Consistency check: All reservations in a segment must be consistent

Generated Parameters

Parameter Description Example
ipv4_addr Interface IP address 192.168.1.1
ipv4_plen Prefix length 24
ipv4_network Network address 192.168.1.0/24

For IPv6 layers, parameters use ipv6_ prefix.

See Template System - Namespace for accessing these in templates.

Cross-Object References

Related object parameters are accessible via prefixes (node_, conn_, opp_, etc.).

See Template System - Namespace for details.

User-defined Parameters (param_rule)

The param_rule section allows defining custom parameter generation rules.

Two Modes

Mode Description Use Case
distribute (default) One value per object Sequential numbering, unique IDs
attach Multiple Values per object VLAN lists, route tables

Distribute Mode (Default)

Distributes parameters across objects, one value per object.

Basic Syntax

param_rule:
  - name: vlan_id
    # mode: distribute  # default, can be omitted
    assign: segment     # "object" (default), "segment", "connection"
    layer: ip           # Required when assign: "segment"
    type: integer       # "integer" (default) or "file"
    min: 100
    max: 999
    header: vlan
    footer: ""

Assignment Scope

Assign Behavior
object (default) Unique value per object
segment Same value for all interfaces in a network segment
connection Same value for both ends of a connection

Source Types

Integer Type (default)

Generates sequential numbers:

param_rule:
  - name: as_number
    type: integer
    min: 65001
    max: 65100
    header: ""
    footer: ""

Result: 65001, 65002, 65003, ...

File Type

Reads values from a file (one value per line):

param_rule:
  - name: hostname
    type: file
    sourcefile: ./hostnames.txt

hostnames.txt:

router-tokyo
router-osaka
router-nagoya

Result: First object gets router-tokyo, second gets router-osaka, etc.

Usage in Classes

Reference in class definition via params:

interface_class:
  - name: trunk
    params: [vlan_id]
    config:
      - name: vlan_config
        template:
          - "switchport trunk allowed vlan {{ .vlan_id }}"

Attach Mode (Value Class)

Attaches multiple parameter sets (Values) to a single object.

Basic Syntax

param_rule:
  - name: vlan_ids
    mode: attach
    source:
      type: range    # "range", "sequence", "list", "file"
      start: 100
      end: 102
    param_format:
      vlan_id: "{{ .value }}"
    config:
      - name: vlan_entry
        template:
          - "vlan {{ .vlan_id }}"

Source Types

range

Generates integer sequence:

source:
  type: range
  start: 100
  end: 103    # exclusive: generates 100, 101, 102

Generated Values (before param_format):

[
  { "value": "100", "index": "0" },
  { "value": "101", "index": "1" },
  { "value": "102", "index": "2" }
]

sequence

Same as range (for compatibility):

source:
  type: sequence
  start: 1
  end: 5

list

Explicit value list with multiple parameters per Value:

source:
  type: list
  values:
    - { network: "10.0.0.0/8", gateway: "192.168.1.1", metric: "100" }
    - { network: "172.16.0.0/12", gateway: "192.168.1.2", metric: "200" }

Generated Values:

[
  { "network": "10.0.0.0/8", "gateway": "192.168.1.1", "metric": "100", "index": "0" },
  { "network": "172.16.0.0/12", "gateway": "192.168.1.2", "metric": "200", "index": "1" }
]

file

Reads values from a file. The format is auto-detected from the file extension, or can be explicitly specified.

Supported Formats:

Extension Format Description
.yaml, .yml yaml YAML array of objects
.json json JSON array of objects
.csv csv CSV with header row
other text One value per line (default)

Text format (default):

source:
  type: file
  file: ./vlans.txt

vlans.txt:

100
101
102

Generated Values:

[
  { "value": "100", "index": "0" },
  { "value": "101", "index": "1" },
  { "value": "102", "index": "2" }
]

YAML format:

source:
  type: file
  file: ./routes.yaml

routes.yaml:

- network: "10.0.0.0/8"
  gateway: "192.168.1.1"
- network: "172.16.0.0/12"
  gateway: "192.168.1.2"

Generated Values:

[
  { "network": "10.0.0.0/8", "gateway": "192.168.1.1", "index": "0" },
  { "network": "172.16.0.0/12", "gateway": "192.168.1.2", "index": "1" }
]

JSON format:

source:
  type: file
  file: ./routes.json

routes.json:

[
  {"network": "10.0.0.0/8", "gateway": "192.168.1.1"},
  {"network": "172.16.0.0/12", "gateway": "192.168.1.2"}
]

CSV format:

source:
  type: file
  file: ./routes.csv

routes.csv:

network,gateway,metric
10.0.0.0/8,192.168.1.1,100
172.16.0.0/12,192.168.1.2,200

Generated Values:

[
  { "network": "10.0.0.0/8", "gateway": "192.168.1.1", "metric": "100", "index": "0" },
  { "network": "172.16.0.0/12", "gateway": "192.168.1.2", "metric": "200", "index": "1" }
]

Explicit format override:

Use format to override auto-detection:

source:
  type: file
  file: ./data.txt
  format: yaml    # Parse as YAML despite .txt extension

Parameter Formatting (param_format)

The param_format field formats source values into Value parameters:

param_rule:
  - name: vlans
    mode: attach
    source:
      type: range
      start: 100
      end: 103
    param_format:
      vlan_id: "{{ .value }}"
      vlan_name: "VLAN{{ .value }}"

Result:

[
  { "vlan_id": "100", "vlan_name": "VLAN100", "index": "0" },
  { "vlan_id": "101", "vlan_name": "VLAN101", "index": "1" },
  { "vlan_id": "102", "vlan_name": "VLAN102", "index": "2" }
]

Config Block Generation

Each Value generates its own config block via config:

param_rule:
  - name: vlans
    mode: attach
    source:
      type: list
      values:
        - { id: "100", name: "mgmt" }
        - { id: "101", name: "data" }
    config:
      - name: vlan_entry
        template:
          - "vlan {{ .id }}"
          - " name {{ .name }}"

Generated config blocks:

vlan 100
 name mgmt
vlan 101
 name data

Referencing Values in Class Templates

Use values_ prefix to embed aggregated Value config blocks:

node_class:
  - name: switch
    params: [vlans]
    config:
      - file: switch.conf
        template:
          - "! VLAN Configuration"
          - "{{ .values_vlan_entry }}"

Output:

! VLAN Configuration
vlan 100
 name mgmt
vlan 101
 name data

Complete Examples

Example 1: VLAN Assignment per Segment

param_rule:
  - name: vlan_id
    assign: segment
    layer: ip
    min: 100
    header: ""

interface_class:
  - name: access_port
    params: [vlan_id]
    config:
      - name: port_config
        template:
          - "switchport mode access"
          - "switchport access vlan {{ .vlan_id }}"

Example 2: Static Routes with Attach Mode

param_rule:
  - name: static_routes
    mode: attach
    source:
      type: list
      values:
        - { network: "10.0.0.0/8", gateway: "192.168.1.1" }
        - { network: "172.16.0.0/12", gateway: "192.168.1.2" }
        - { network: "0.0.0.0/0", gateway: "192.168.1.254" }
    config:
      - name: route_entry
        template:
          - "ip route {{ .network }} {{ .gateway }}"

node_class:
  - name: router
    params: [static_routes]
    config:
      - file: router.conf
        template:
          - "! Routing Configuration"
          - "{{ .values_route_entry }}"

Example 3: Reading VLANs from File

param_rule:
  - name: allowed_vlans
    mode: attach
    source:
      type: file
      file: ./allowed_vlans.txt
    param_format:
      vlan_id: "{{ .value }}"
    config:
      - name: vlan_permit
        format: comma_list
        template:
          - "{{ .vlan_id }}"

interface_class:
  - name: trunk_port
    params: [allowed_vlans]
    config:
      - name: trunk_config
        template:
          - "switchport mode trunk"
          - "switchport trunk allowed vlan {{ .values_vlan_permit }}"

allowed_vlans.txt:

100
101
200

Output:

switchport mode trunk
switchport trunk allowed vlan 100,101,200

The format: comma_list option uses FormatStyle to join values with commas.

Summary: Choosing the Right Approach

Scenario Mode Type/Source
Unique ID per object distribute integer
Same value per segment distribute (assign: segment) integer
Names from file distribute file
Multiple VLANs per switch attach range or list
Static routes per router attach list
Dynamic list from file attach file

Clone this wiki locally