vnetbuild.conf - VNetBuild configuration file
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*
...
...There is no default configuration file for vnetbuild(1); one must always be specified on the command line.
The configuration file defines a set of namespaces that will be operated on.
VNetBuild defines two types of namespace, a host and a
switch. Any number of each may be specified, with any
number of configuration statements in each.
host
and a switch namespace. VNetBuild provides the distinction
to make it easy build full virtual networks.
Namespace definitions come in two types, host and
switch. Simply provide a simple unique alphanumeric
ID. Any subsequent statements apply to this namespace until the
next host or switch statement.
A host definition is designed to work like a physical
machine. It allows you to 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 provides a
route statement to deal with the common case of wanting to
add network routes to the host.
A switch definition is designed to work like a physical
network switch. It allows you to add any number of dev
entries (and also custom exec commands for extensibility)
but nothing else.
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.
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/veth0Any 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.
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/24A 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.
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/8Devices included in a bridge generally do not need their own IP address (although that is permitted).
Bridges cannot have a pair themselves, but any devices added to a bridge need a pair as usual.
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.254The syntax of ROUTECMD is anything that can fit this pattern:
ip route add ROUTECMDSee 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.
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.
See below for some common uses for custom pre_up and
exec commands.
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.shSee below for some common uses for custom pre_up and
exec 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 startForwarding 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_forwardThe exec operates in the mygateway
namespace so your host is not affected.
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_stateYou 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_snoopingIt 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.confThe -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.
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_forwardWhen 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 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.