This repository is a record of my personal experiments on VIMAGE jails
and netgraph modules with customized scripts which originally come with
the FreeBSD source tree (in share/examples/jails).

My primary goal is modifying 'jng' script to support internal virtual
network (host-only or routed topology) in combination with /etc/jail.conf.

After experimenting for a while, I decided to write a new script 'vnet'
based on 'jng'.

	  |
	  | external I/F
	  o                virtual bridge (switch)
	[host]o---------[vi0br]
	      vi0        | | |   vi0_h1
            internal I/F | | +--------o (for jail [h1])
                         | |
                         | |     vi0_h2
                         | +----------o (for jail [h2])
                         |
                         |       vi0_h3
                         +------------o (for jail [h3])

Using this script, the above network is created by running the follwing
command.

	vnet add vi0 vi0_h1 vi0_h2 vi0_h3

The first argument of 'vnet add' is the name of a host interface which
will be also used in a bridge name for the network by appending 'br'.

The host interface can be a physical ethernet (type ether) or a virtual
one (type eiface). If the specified host interface doesn't exist,
a virtual interface with the name will be automatically created.

Subsequent arguments are virtual intefaces for jails. They will be also
automatically created.

Actually, 'vnet add' can take -4 and -6 options which specify an IPv4
 and IPv6 address/prefix length respectively.

Using this script, /etc/jail.conf for VIMAGE jails can be something
like below. Of course, you can enable IP forwarding and NAT on the host
to allow the jails to go out to the Internet.

exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
exec.clean;
mount.devfs;

host.hostname = $name;
path = "/vm/$name";
exec.consolelog = "/var/log/jail_${name}_console.log";

xxx {
	$net = "vi0";
	$gwv4 = "172.31.0.1";
	$ipv4 = "172.31.0.11";
	$plen = 24;

	vnet;
	vnet.interface = "${net}_$name";
	exec.prestart += "vnet add -4 $gwv4/$plen $net ${net}_$name";
	exec.start    += "ifconfig ${net}_$name $ipv4/$plen";
	exec.start    += "route add default $gwv4";
	exec.poststop += "vnet delete $net ${net}_$name";
}


You can also create a network without any connection to the host,
thus outside world.

	  |
	  | external I/F
	  o                virtual bridge (switch)
	[host]          [vi0br]
	                 | | |   vi0_h1
                         | | +--------o (for jail [h1])
                         | |
                         | |     vi0_h2
                         | +----------o (for jail [h2])
                         |
                         |       vi0_h3
                         +------------o (for jail [h3])

This can be done with -b (bridge only) option to vnet add.

	vnet add -b vi0 vi0_h1 vi0_h2 vi0_h3


Please note that the vnet script is intended only for creating
and connecting interfaces and bridges for use with VNET jails.

Use /etc/jail.conf for assigning interfaces to jails, setting IP
address on the interfaces and so on.


For more configurations and details, please look at jail.vnet.*.conf
in this repository and/or visit the following URL.
https://genneko.github.io/playing-with-bsd/system/learning-notes-on-jails/#vnet-jails




ORIGINAL CONTENT OF THIS FILE

# $FreeBSD: releng/11.2/share/examples/jails/README 295542 2016-02-11 18:37:02Z dteske $

The below 4 samples require a VIMAGE enabled kernel:

	# (as root)
	$ cp VIMAGE /usr/src/sys/amd64/conf/
	$ cd /usr/src
	$ make KERNCONF=VIMAGE kernel
	$ reboot

Sample 1: jail.conf(5)

	$ cp jib jng /usr/sbin/
	$ cat jail.xxx.conf >> /etc/jail.conf
	$ vi /etc/jail.conf
	# NB: Customize root directory and bridge interface
	$ sysrc jail_enable=YES
	# NB: Assumes jail_list="" (meaning ``all jails in jail.conf'')
	# NB: Assumes rc_conf_files="" (``below rc.conf(5) samples not used'')
	$ service jail start

Sample 2: rc.conf(5)

	$ cp jib jng /usr/sbin/
	$ cp rc.conf.jails /etc/
	$ vi /etc/rc.conf.jails
	# NB: Customize root directory and bridge interface
	$ sysrc rc_conf_files+=/etc/rc.conf.jails
	# NB: Assumes /etc/jail.conf does not exist and jail_list=""
	$ service jail start

Sample 3: Per-jail jail.conf(5)

	$ cp jib jng /usr/sbin/
	$ cp jail.xxx.conf /etc/
	$ vi /etc/jail.xxx.conf
	# NB: Customize root directory and bridge interface
	$ sysrc jail_enable=YES
	$ sysrc jail_list+=xxx
	# NB: Assumes rc_conf_files=""
	$ service jail start

Sample 4: Per-jail rc.conf(5)

	$ cp jib jng /usr/sbin/
	$ cp rcjail.xxx.conf /etc/
	$ vi /etc/rcjail.xxx.conf
	# NB: Customize root directory and bridge interface
	$ sysrc jail_enable=YES
	$ sysrc jail_list+=xxx
	$ sysrc rc_conf_files+=/etc/rcjail.xxx.conf
	# NB: Assumes neither /etc/jail.conf nor /etc/jail.xxx.conf exist
	$ service jail start

For additional recipes, see share/examples/netgraph for
making and hooking together jails using netgraph as the
virtual networking fabric.