Skip to content

Upgrading to 0.8

Jump to bottom
sat edited this page Aug 15, 2026 · 12 revisions

Upgrading to 0.8.0

A topology written for 0.7.x meets several changes at once. This page is what to read before upgrading one; the CHANGELOG describes each in full.

Generated files move

A file declared with path: /etc/frr/frr.conf is written to r1/etc/frr/frr.conf, not r1/frr.conf. A node's files are laid out by the path they take inside the container.

What to do: nothing in the topology. Anything reading generated files by path has to follow — a script of your own, or a downstream tool such as netroub, which reads a lab's generated files to replay failures on it. See File Output.

Interfaces are named eth0, eth1, ...

The default interface prefix is eth, where it used to be net.

What to do: update any template that names an interface literally. eth is what a Linux container calls its interfaces and the only prefix Kathara accepts, so this is the one name every platform agrees on.

containerlab nodes get no management network

Generated nodes carry network-mode: none. A lab has only the links its topology describes.

What to do: if the lab relied on clab exec, the clab-* container names, or reachability through the management network, put it back:

module_config:
  containerlab:
    management_network: true

and name the data interfaces something other than eth0, which containerlab keeps for itself.

A shared segment reaching across machines is replaced with bridges

A multi-host topology that drew a segment spanning machines now gets one bridge per machine, linked to each other, instead of one link leaving a machine per member on the far side.

What to do: nothing, unless the old shape was wanted: global.aggregate_crossing_links: false.

virtual no longer means "not deployed"

One flag used to answer two questions — is this object there? and does dot2net write its configuration? — and a topology could not answer them separately. In 0.8.0 they are two settings:

  • deploy says what the object is materialised as. On a node, container (the default) · platform · none. On an interface or a connection, link · logical · none.
  • virtual: true says only that this object's own configuration is not written. It means the same thing on every kind of class, and it no longer has any bearing on whether the object is deployed.

What to do: replace virtual: true with deploy: none wherever it meant "this is not deployed" — which is what it meant on a node, and what it usually meant on an interface or a connection.

# 0.7.x                        # 0.8.0
nodeclass:                     nodeclass:
  - name: vrouter                - name: vrouter
    virtual: true                  deploy: none

connectionclass:               connectionclass:
  - name: v                      - name: v
    virtual: true                  deploy: logical   # a tunnel the configuration builds

You do not have to find them by reading. A class that sets virtual: true without also naming a deploy is an error, so a topology written for 0.7.x stops on the first one and tells you what to write instead. The error is a migration aid and is removed in 0.9.0; until then, saying which one you mean is required.

Choose deploy: logical rather than none for a connection that is not wired by the platform but is built by the configuration running on the nodes — a VXLAN overlay or a GRE tunnel. Its endpoints are real devices and still get their configuration; only the wiring is absent.

deploy: none and virtual can now also be combined, which the single flag could not express: deploy: container with virtual: true is a node that starts like any other and that dot2net writes no configuration into.

Mistakes that used to be quiet are now errors

What Why
An unknown or duplicate key in the config file A key the config did not know was dropped without a word, which looks exactly like a setting that had no effect
Two file definitions writing the same file Whichever was written last won, and the other's content was gone
A config entry naming both template and sourcefile Which came first was decided in the code and written down nowhere

What to do: run dot2net build and fix what it names. Each message says what is wrong and how to write it instead.

The Kathara startup file

0.7.0 documented writing <device>.startup yourself, with name_suffix: .startup and output: root. The Kathara module owns that file now.

What to do: if the topology declared it, drop the declaration and write a startup template instead — the same one containerlab and TiNET already read:

nodeclass:
  - name: router
    config:
      - name: startup
        template:
          - "ip link set lo up"

The old declaration still works on its own; it collides once the Kathara module is loaded, and dot2net says which two definitions collided.

See Also

Clone this wiki locally