add utility to simplify use of ng_wormhole

[dave_freedave.net]

Summary

This is the last of a series that began with D50241 and D50244.

Creating, opening, naming, and finally attaching wormholes is a lot of ngctl(8) commands. This squashes the whole thing into one command.
It does this while being completely generic. It doesn't need to know anything about other netgraph(8) nodes.

Test Plan

As promises we are going to recreate https://wiki.freebsd.org/VIMAGE/VNETSamples but with ng_wormhole(4) and ng_eiface(4).

create 3 jails (left, center, and right):

jail -i -c name=left   host.hostname=left.example.net   vnet persist
jail -i -c name=center host.hostname=center.example.net vnet persist
jail -i -c name=right  host.hostname=right.example.net  vnet persist

create ngeth0a in left

kldload ng_eiface
echo -e "mkpeer eiface e ether\nname .:e ngeth0a" | ngctl -j left -f -
ifconfig -j left `ngctl -j left msg ngeth0a: getifname | sed '1d' | cut -d\" -f2` name ngeth0a

create ngeth0b and ngeth1a in center

echo -e "mkpeer eiface e ether\nname .:e ngeth0b" | ngctl -j center -f -
ifconfig -j center `ngctl -j center msg ngeth0b: getifname | sed '1d' | cut -d\" -f2` name ngeth0b
echo -e "mkpeer eiface e ether\nname .:e ngeth1a" | ngctl -j center -f -
ifconfig -j center `ngctl -j center msg ngeth1a: getifname | sed '1d' | cut -d\" -f2` name ngeth1a

create ngeth1b in right

echo -e "mkpeer eiface e ether\nname .:e ngeth1b" | ngctl -j right -f -
ifconfig -j right `ngctl -j right msg ngeth1b: getifname | sed '1d' | cut -d\" -f2` name ngeth1b

Now get ready for the simplicity of using the portal gun to connect everything:

ngportal left:wh0a:ngeth0a:ether center:wh0b:ngeth0b:ether
ngportal center:wh1a:ngeth1a:ether right:wh1b:ngeth1b:ether

That saved us so much typing! But let's make sure things actually work. Configure IPv4 and IPv6 for left:

ifconfig -j left ngeth0a inet 192.0.2.1/30 up
ifconfig -j left ngeth0a inet6 fdc5::1/64 alias

configure IPv4 and IPv6 for center

ifconfig -j center ngeth0b inet 192.0.2.2/30 up
ifconfig -j center ngeth0b inet6 fdc5::2/64 alias
ifconfig -j center ngeth1a inet 192.0.2.5/30 up
ifconfig -j center ngeth1a inet6 fdc5:1::5/64 alias

configure IPv4 and IPv6 for right

ifconfig -j right ngeth1b inet 192.0.2.6/30 up
ifconfig -j right ngeth1b inet6 fdc5:1::6/64 alias

do the simple ping tests:

jexec center ping  -c 1 -n 192.0.2.1
jexec center ping  -c 1 -n 192.0.2.6
jexec center ping6 -c 5 -n fdc5::1
jexec center ping6 -c 5 -n fdc5:1::6

allow center to route packets:

jexec center sysctl net.inet.ip.forwarding=1
jexec center sysctl net.inet6.ip6.forwarding=1

set up routes:

jexec left route add -inet default 192.0.2.2
jexec left route add -inet6 default fdc5::2
jexec right route add -inet default 192.0.2.5
jexec right route add -inet6 default fdc5:1::5

finally traceroute test:

jexec left traceroute -n 192.0.2.6
jexec left traceroute6 -n fdc5:1::6

Oh and have you noticed no wormhole was left in the sytem? For that magic to work you actually created two pairs of wormholes then connected the event horizon of the wormholes left on the system. That collapsed down to one wormhole in one jail and another in another jail, but nothing in the system. Take a look!

ngctl ls
ngctl -j center ls

Cleanup time! In this case you just remove the jails as nothing was created outside of them:

jail -r center
jail -r left
jail -r right

To match my picture I did name the wormholes but that is entirely optional.

[dave_freedave.net]

Fix source file license per @ziaee (comment was in D50241).

[dave_freedave.net]

Fixed man page to be mandoc -Tlint compliant.
Saw a style issue in Usage() and fixed it.
parse_spec() was giving errors about "component[x]" which has no meaning at all to users of ngportal and was changed to display the component with an error which should be much more helpful.

[dave_freedave.net]

Document that you must leave the jail empty to indicate the jail where you run ngportal.

I can't find a way to get the jail ID. procstat_getprocs always returns 0 for JID as does sysctl security.jail.param.jid. kvm_getprocs also won't work as you don't know if you have /dev/mem available and it also just seems to return 0 for JID. Searching bugs and found nothing so I don't think anybody wants/needs this and its best we just live without it too and fix in documentation.

[dave_freedave.net]

Most up to date version is at https://github.com/dmarker/bong-utils