.\" Automatically generated by Pandoc 2.9.2.1
.nh
.\"
.TH "vnetbuild.conf" "5" "Built 28 Feb 2021" "VNetBuild Reference" "3.1.7"
.hy
.SH NAME
.PP
vnetbuild.conf - VNetBuild configuration file
.SH SYNOPSIS
.IP
.nf
\f[C]
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*
    ...

\&...
\f[R]
.fi
.SH DESCRIPTION
.PP
There is no default configuration file for vnetbuild(1); one must always
be specified on the command line.
.PP
The configuration file defines a set of namespaces that will be operated
on.
.PP
VNetBuild defines two types of namespace, a \f[C]host\f[R] and a
\f[C]switch\f[R].
Any number of each may be specified, with any number of configuration
statements in each.
.TP
Note
The Linux kernel does not see any difference between a \f[C]host\f[R]
and a \f[C]switch\f[R] namespace.
VNetBuild provides the distinction to make it easy build full virtual
networks.
.SH NAMESPACE DEFINITIONS
.PP
Namespace definitions come in two types, \f[C]host\f[R] and
\f[C]switch\f[R].
Simply provide a simple unique alphanumeric \f[I]ID\f[R].
Any subsequent statements apply to this namespace until the next
\f[C]host\f[R] or \f[C]switch\f[R] statement.
.PP
A \f[C]host\f[R] definition is designed to work like a physical machine.
It allows you to specify any number of \f[C]dev\f[R] entries for network
interfaces, with their IP addresses.
You can also define any number of Linux bridges with \f[C]bridgedev\f[R]
to add your defined interfaces to.
.PP
A \f[C]host\f[R] also allows any number of custom \f[C]exec\f[R]
commands for extensibility and provides a \f[C]route\f[R] statement to
deal with the common case of wanting to add network routes to the host.
.PP
A \f[C]switch\f[R] definition is designed to work like a physical
network switch.
It allows you to add any number of \f[C]dev\f[R] entries (and also
custom \f[C]exec\f[R] commands for extensibility) but nothing else.
.PP
In addition, \f[C]dev\f[R] entries in a \f[C]switch\f[R] may only
specify device names, they cannot have an IP address associated.
A \f[C]switch\f[R] has a bridge automatically created in it and all
\f[C]dev\f[R] entries are automatically added to it.
.SH CONFIGURATION STATEMENTS
.TP
dev \f[I]DEVICE\f[R] \&...
Define a virtual ethernet device, \f[I]DEVICE\f[R] in a \f[C]host\f[R]
or \f[C]switch\f[R].
.RS
.PP
Devices must exist in pairs.
A \f[C]dev\f[R] must first be defined unpaired in a namespace, then some
subsequent \f[C]dev\f[R] must define the pair:
.IP
.nf
\f[C]
host a
  dev veth0
host b
  dev vppp0 a/veth0
\f[R]
.fi
.PP
Any \f[I]DEVICE\f[R] name which is acceptable to the Linux kernel may be
used.
We recommend sticking to e.g.\ \f[C]veth0\f[R], \f[C]vppp0\f[R] 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 \f[C]veth\f[R], irrespective of what you
call them.
.PP
Hosts may optionally specify one or more \f[I]IP\f[R]/\f[I]MASK\f[R]
values which will be applied (along with the calculated broadcast
address) automatically, e.g.:
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
A \f[C]dev\f[R] may not specify an IP address if it is in a
\f[C]switch\f[R].
Switches exist just to tie together multiple devices in hosts, just like
a physical network switch.
.RE
.TP
bridgedev \f[I]BRIDGE\f[R] \&...
Define an ethernet bridge, \f[I]BRIDGE\f[R] in a \f[C]host\f[R].
These are setup automatically using ip(8) and shown with bridge(8).
.RS
.PP
A bridge can specify network devices from its own namespace to be
automatically added, as well as its own IP address(es).
.IP
.nf
\f[C]
host a
  dev veth0
  dev veth1 otherns/vdev0
  bridgedev vbr0 veth0 veth1 10.0.0.3/8
\f[R]
.fi
.PP
Devices included in a bridge generally do not need their own IP address
(although that is permitted).
.PP
Bridges cannot have a pair themselves, but any devices added to a bridge
need a pair as usual.
.RE
.TP
route \f[I]ROUTECMD\f[R]
Specify an additional network route for a \f[C]host\f[R].
.RS
.PP
Most commonly to add a default route from hosts on a \[lq]LAN\[rq] to
the machine that acts as a gateway, e.g.:
.IP
.nf
\f[C]
route default via 10.0.0.254
\f[R]
.fi
.PP
The syntax of \f[I]ROUTECMD\f[R] is anything that can fit this pattern:
.IP
.nf
\f[C]
ip route add ROUTECMD
\f[R]
.fi
.PP
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 \f[C]exec\f[R] configuration statement.
.RE
.TP
pre_up \f[I]DEVICE\f[R] \f[I]CUSTOMCMD\f[R]
Execute custom commands in a \f[C]host\f[R] or \f[C]switch\f[R] just
before bringing up the specified device.
All of the \f[C]pre_up\f[R] statements for a device are combined and
executed in the namespace.
.RS
.PP
In addition to any explicitly defined interfaces, switches have an
implicit bridge device called \f[C]switch\f[R] which can also be used in
\f[C]pre_up\f[R] commands.
.PP
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 \f[C]pre_up\f[R] on the first defined \f[C]dev\f[R].
.PP
See below for some common uses for custom \f[C]pre_up\f[R] and
\f[C]exec\f[R] commands.
.RE
.TP
exec \f[I]CUSTOMCMD\f[R]
Execute a custom command in a \f[C]host\f[R] or \f[C]switch\f[R] once
the rest of the namespace setup is complete.
.RS
.PP
Once all the namespaces are created, the final step in setting each one
up is to have its \f[C]exec\f[R] statements combined and executed.
.PP
It is roughly the equivalent to writing your own script and executing it
after \f[C]vnetbuild start\f[R] has finished:
.IP
.nf
\f[C]
sudo ip netns exec myns ./myscript.sh
\f[R]
.fi
.PP
See below for some common uses for custom \f[C]pre_up\f[R] and
\f[C]exec\f[R] commands.
.RE
.SH COMMON CUSTOM COMMANDS
.PP
For the most part it doesn\[cq]t matter whether these commands are used
in \f[C]pre_up\f[R] or \f[C]exec\f[R] 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 \f[C]pre_up\f[R] of
the first device.
If you only want the firewall after all devices are up, put it in
\f[C]exec\f[R], e.g.:
.IP
.nf
\f[C]
host myfirewall
    ...
    exec firehol myfirewall.conf start
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
host mygateway
    ...
    exec echo 1 > /proc/sys/net/ipv4/ip_forward
\f[R]
.fi
.PP
The \f[C]exec\f[R] operates in the \f[C]mygateway\f[R] namespace so your
host is not affected.
.PP
Bridges are created without STP being enabled.
To enable STP to ensure loops are not created, the following can be
done:
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
You could also use \f[C]brctl stp vbr0 on\f[R] and
\f[C]brctl stp switch on\f[R] instead of setting the values directly.
To disable multicast snooping you can use exactly the same method e.g.:
.IP
.nf
\f[C]
switch myswitch
    ...
    pre_up switch echo 0 > /sys/class/net/switch/bridge/multicast_snooping
\f[R]
.fi
.PP
It is possible to run firehol within a namespace to set up custom
.PP
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 \f[I]ULOG\f[R] or \f[I]NFLOG\f[R] logging.
For FireHOL, that means set \f[C]FIREHOL_LOG_MODE=ULOG\f[R] or
\f[C]FIREHOL_LOG_MODE=NFLOG\f[R].
Note that \f[I]NFLOG\f[R] only works with ulogd version 2.
.PP
The default configuration for ulogd(8) is \f[C]/etc/ulogd.conf\f[R].
Assuming the default place it will write iptables logs to is
\f[C]/var/log/ulog/syslogemu.log\f[R] (otherwise change the
\f[C]sed\f[R] command as required), it is simple to set up per-namespace
logging:
.IP
.nf
\f[C]
host mygateway
  ...
  exec sed \[aq]s:/var/log/ulog/syslogemu.log:/var/log/ulog/mygateway.log:\[aq] /etc/ulogd.conf > $NSTMP/ulogd.conf
  exec /usr/sbin/ulogd -d -c $NSTMP/ulogd.conf
\f[R]
.fi
.PP
The \f[C]-d\f[R] flag to ulogd(8) makes it become a daemon; when
\f[C]vnetbuild stop\f[R] executes it will automatically kill any
programs running in the namespaces is is stopping, which includes the
logging daemon.
.PP
The configuration file will get cleaned as soon as
\f[C]vnetbuild start\f[R] is finished.
To be able to access such files you need to write them to a location not
under \f[C]$NSTMP\f[R] or create them outside the \f[C]vnetbuild\f[R]
configuration altogether.
.SH EXAMPLE
.PP
A simple LAN arrangement with two hosts, one of which is a gateway to
third host:
.IP
.nf
\f[C]
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
\f[R]
.fi
.SH LIMITATIONS
.PP
When created, the namespaces setup by \f[C]vnetbuild\f[R] are completely
disconnected from any real network.
There is no way of defining such a connection in the \f[C]vnetbuild\f[R]
configuration as allowing it would lead to conflicts with the normal
network setup tools and configuration files in most distributions.
.PP
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).
.SH SEE ALSO
.IP \[bu] 2
vnetbuild(1) - VNetBuild program
.IP \[bu] 2
FireHOL Website (http://firehol.org/)
.IP \[bu] 2
VNetBuild Online PDF Manual (http://firehol.org/vnetbuild-manual.pdf)
.IP \[bu] 2
VNetBuild Online Documentation (http://firehol.org/documentation/)
.IP \[bu] 2
ip(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ip.8.html) -
show/manipulate network devices
.IP \[bu] 2
ip-route(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ip-route.8.html)
- routing table management
.IP \[bu] 2
bridge(8) (http://manpages.ubuntu.com/manpages/trusty/man8/bridge.8.html)
- routing table management
.IP \[bu] 2
ulogd(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ulogd.8.html)
- netfilter/iptables logging daemon
.SH AUTHORS
FireHOL Team.