vnetbuild.conf(5)

🌸 NAME 🌸

vnetbuild.conf — the VNetBuild configuration file. That's this page, bestie: vnetbuild.conf(5). It's giving "instructions for the whole virtual network" energy 💅

---

✨ SYNOPSIS ✨

host ID
    dev DEVICE [ ID/PAIRDEV ] [ IP/MASK... ]
    ...
    bridgedev BRIDGE [ DEVICE... ] [ IP/MASK... ]
    ...
    route ROUTECMD
    ...
    pre_up DEVICE CUSTOMCMD
    ...
    exec CUSTOMCMD
    ...

...

switch ID
    dev DEVICE [ ID/PAIRDEV ]
    ...
    pre_up DEVICE CUSTOMCMD
    ...
    exec CUSTOMCMD
    ...

...

---

💖 DESCRIPTION 💖

Okay so first thing, no cap: there is no default configuration file for vnetbuild(1). You have to specify one on the command line, every single time. There is no vibe-based autodetection. Periodt. 🎀

The configuration file defines a set of namespaces that will be operated on.

VNetBuild defines two types of namespace: a host and a switch. You can specify any number of each, and each one can hold any number of configuration statements. Go feral, honestly. 🦋

Note — the Linux kernel does not see any difference between a host and a switch namespace. VNetBuild provides the distinction purely to make it easy to build full virtual networks. It's cosmetic for your benefit, not the kernel's. 👑

---

🧚 NAMESPACE DEFINITIONS 🧚

Namespace definitions come in two types: host and switch. You just provide a simple unique alphanumeric ID. Every statement after that applies to this namespace until the next host or switch statement shows up. Slay, simple. ✨

A host definition is designed to work like a physical machine. It lets you specify any number of dev entries for network interfaces, with their IP addresses. You can also define any number of Linux bridges with bridgedev to add your defined interfaces to. 🌈

A host also allows any number of custom exec commands for extensibility, and it provides a route statement to deal with the common case of wanting to add network routes to the host. So thoughtful of it. 🫶

A switch definition is designed to work like a physical network switch. It lets you add any number of dev entries (and also custom exec commands for extensibility) but nothing else. That's it. That's the whole menu. 💀

In addition, dev entries in a switch may only specify device names — they cannot have an IP address associated. A switch has a bridge automatically created in it, and all dev entries are automatically added to it. Automatic queen behaviour. 👑

---

🎀 CONFIGURATION STATEMENTS 🎀

dev DEVICE ...

Define a virtual ethernet device, DEVICE, in a host or switch. 💅

Devices must exist in pairs. A dev must first be defined unpaired in a namespace, then some subsequent dev must define the pair:

host a
  dev veth0
host b
  dev vppp0 a/veth0

Any DEVICE name which is acceptable to the Linux kernel may be used. We recommend sticking to e.g. veth0, vppp0 etc. to make it clear that they are virtual and also how you are thinking of the device in terms of your setup. Devices will be created as type veth, irrespective of what you call them. Name it princess if you want, it's still a veth. 👸

Hosts may optionally specify one or more IP/MASK values which will be applied (along with the calculated broadcast address) automatically, e.g.:

host a
  dev veth0 10.0.0.1/8 192.168.1.2/24
host b
  dev vppp0 a/veth0 10.0.0.2/8 192.168.1.3/24

A dev may not specify an IP address if it is in a switch. Switches exist just to tie together multiple devices in hosts, just like a physical network switch. No IPs for switch devices, I don't make the rules. 🙈

bridgedev BRIDGE ...

Define an ethernet bridge, BRIDGE, in a host. These are setup automatically using ip(8) and shown with bridge(8). ✨

A bridge can specify network devices from its own namespace to be automatically added, as well as its own IP address(es).

host a
  dev veth0
  dev veth1 otherns/vdev0
  bridgedev vbr0 veth0 veth1 10.0.0.3/8

Devices included in a bridge generally do not need their own IP address (although that is permitted). Live your truth either way. 💜

Bridges cannot have a pair themselves, but any devices added to a bridge need a pair as usual.

route ROUTECMD

Specify an additional network route for a host. 🛣️

Most commonly to add a default route from hosts on a “LAN” to the machine that acts as a gateway, e.g.:

route default via 10.0.0.254

The syntax of ROUTECMD is anything that can fit this pattern:

ip route add ROUTECMD

See ip(8) and ip-route(8) for help adding routes. If you want to do anything more complex than simply adding routes, use the exec configuration statement. That's the escape hatch, bestie. 🚪

pre_up DEVICE CUSTOMCMD

Execute custom commands in a host or switch just before bringing up the specified device. All of the pre_up statements for a device are combined and executed in the namespace. 🔥

In addition to any explicitly defined interfaces, switches have an implicit bridge device called switch which can also be used in pre_up commands.

Bridges always start after other devices, so to run a command after all everything has been created but before any interfaces are up, you can make use of pre_up on the first defined dev. Timing is everything, iykyk. ⏰

See below for some common uses for custom pre_up and exec commands.

exec CUSTOMCMD

Execute a custom command in a host or switch once the rest of the namespace setup is complete. ✅

Once all the namespaces are created, the final step in setting each one up is to have its exec statements combined and executed.

It is roughly the equivalent to writing your own script and executing it after vnetbuild start has finished:

sudo ip netns exec myns ./myscript.sh

See below for some common uses for custom pre_up and exec commands.

---

🌈 COMMON CUSTOM COMMANDS 🌈

For the most part it doesn't matter whether these commands are used in pre_up or exec operations — the only difference is when they will execute. So e.g. if you want a firewall in place before any interfaces come up, then start it from the pre_up of the first device. If you only want the firewall after all devices are up, put it in exec, e.g.:

host myfirewall
    ...
    exec firehol myfirewall.conf start

Forwarding is not enabled by the Linux kernel when a namespace is first created. This can be easily done for any hosts that need to forward traffic:

host mygateway
    ...
    exec echo 1 > /proc/sys/net/ipv4/ip_forward

The exec operates in the mygateway namespace so your host is not affected. Your actual machine stays unbothered, as it should. 💅

Bridges are created without STP being enabled. To enable STP to ensure loops are not created, the following can be done:

host myhost
    bridgedev vbr0 ...
    ...
    pre_up vbr0 echo 2 > /sys/class/net/vbr0/bridge/stp_state

switch myswitch
    ...
    pre_up switch echo 2 > /sys/class/net/vbr0/bridge/stp_state

You could also use brctl stp vbr0 on and brctl stp switch on instead of setting the values directly. To disable multicast snooping you can use exactly the same method e.g.:

switch myswitch
    ...
    pre_up switch echo 0 > /sys/class/net/switch/bridge/multicast_snooping

It is possible to run firehol within a namespace to set up custom

Logs from network namespaces are not included in the normal system logs. To enable iptables logging you must start an instance of ulogd(8) in the namespace and use ULOG or NFLOG logging. For FireHOL, that means set FIREHOL_LOG_MODE=ULOG or FIREHOL_LOG_MODE=NFLOG. Note that NFLOG only works with ulogd version 2. 👀

The default configuration for ulogd(8) is /etc/ulogd.conf. Assuming the default place it will write iptables logs to is /var/log/ulog/syslogemu.log (otherwise change the sed command as required), it is simple to set up per-namespace logging:

host mygateway
  ...
  exec sed 's:/var/log/ulog/syslogemu.log:/var/log/ulog/mygateway.log:' /etc/ulogd.conf > $NSTMP/ulogd.conf
  exec /usr/sbin/ulogd -d -c $NSTMP/ulogd.conf

The -d flag to ulogd(8) makes it become a daemon; when vnetbuild stop executes it will automatically kill any programs running in the namespaces is is stopping, which includes the logging daemon.

The configuration file will get cleaned as soon as vnetbuild start is finished. To be able to access such files you need to write them to a location not under $NSTMP or create them outside the vnetbuild configuration altogether. So don't go storing your precious files under $NSTMP, they're getting yeeted. 😭

---

🦋 EXAMPLE 🦋

A simple LAN arrangement with two hosts, one of which is a gateway to third host:

host host01
  dev veth0 10.0.0.1/8
  dev vppp0 192.168.0.1/24
  exec echo 1 > /proc/sys/net/ipv4/ip_forward
  route default via 192.168.0.1

host host02
  dev veth0 10.0.0.2/8
  route default via 10.0.0.1

switch lan
  dev d01 host01/veth0
  dev d02 host02/veth0

host extern01
  dev veth0 host01/vppp0 192.168.0.254/24
  route default via 192.168.0.1
  exec echo 1 > /proc/sys/net/ipv4/ip_forward

---

💀 LIMITATIONS 💀

When created, the namespaces setup by vnetbuild are completely disconnected from any real network. There is no way of defining such a connection in the vnetbuild configuration, as allowing it would lead to conflicts with the normal network setup tools and configuration files in most distributions. It's not a bug, it's a boundary. 🚧

It is possible to arrange your network so you can connect real devices into one or more network namespaces. For the general approach see this mailing list post:

http://lists.firehol.org/pipermail/firehol-support/2015-April/003043.html

---

👑 SEE ALSO 👑

• vnetbuild(1) — VNetBuild program
• FireHOL Website
• VNetBuild Online PDF Manual
• VNetBuild Online Documentation
• ip(8) — show/manipulate network devices
• ip-route(8) — routing table management
• bridge(8) — routing table management
• ulogd(8) — netfilter/iptables logging daemon

---

🫶 AUTHORS 🫶

FireHOL Team.

---

And that's a wrap, bestie — this page came from the VNetBuild Reference, built 13 Apr 2025, running version 3.1.8. Go forth and build your little network empire. Slay. 💖✨