create netgraph ng_wormhole node type

[dave_freedave.net]

Summary

This is a new node type that allows netgraph nodes that are in different vnet(9)s to be connected. It absolutely does add an extra pair of function calls as data goes from one node to its wormhole, on to the next wormhole, and finally back out to another node.

But you will never pay more than that price as connecting two wormholes will cause collapse of one pair leaving behind only one pair.

For this to work you must mkpeer wormhole w evthorizon and separately open the wormhole into another jail. This creates the connected pair. The pair hold each other open, but until then they will shutdown when nothing is connected so you need to create with something like:

ngctl -f- << EOF
mkpeer wormhole w evthorizon
name .:w wh0
msg wh0: open “testjail"
EOF

This is intentionally minimalist and wormholes also have strict invariants:

1. Both ends can NOT be in the same vnet(9), ever.
   • if they were you wouldn't need the wormhole!
2. If you connect the evthorizon of two wormholes they collapse
   • As a consequence you can never have more than 2 extra function calls
3. Wormholes can only be opened once.
4. If either side of a wormhole is shutdown they both shutdown
   • As a consequence you don’t have to clean up on jail shutdown.

Test Plan

This assumes we already have D50241 available but I still consider this the "hard way":

jail -i -c name=demo host.hostname=demo.example.net vnet persist
kldload ng_eiface

echo -e "mkpeer eiface e ether\nname .:e ngeth0a" | ngctl -f -
echo -e "mkpeer eiface e ether\nname .:e ngeth0b" | ngctl -j demo -f -
ngctl mkpeer ngeth0a: wormhole ether evthorizon
ngctl msg ngeth0a:ether open '"demo"'

We still have one connection to make, but here we need to examine our current wormhole:

ngctl show ngeth0a:ether
  Name: <unnamed>       Type: wormhole        ID: 00000018   Num hooks: 2
  Local hook      Peer name       Peer type    Peer ID         Peer hook
  ----------      ---------       ---------    -------         ---------
  jid=1           <unnamed>       wormhole     0000000d        jid=0
  evthorizon      ngeth0a         eiface       0000000c        ether

That is intentional trickery in that we name the warp hook after the JIDs on either side. This matters because you need to know how to get to "the far side". In this case jail "demo" is JID 1 and the wormhole has ID 0000000d (these are unique per vnet!).

Ok assuming you adjust for your IDs you finally connect in the jail with:

ngctl -j 1 connect ngeth0b: [0000000d]: ether evthorizon

Just to be sure it actually works though lets do something trivial:

ifn=$(ngctl msg ngeth0a: getifname | sed '1d' | cut -d\" -f2)
ifconfig $ifn name ngeth0a
ifn=$(ngctl -j 1 msg ngeth0b: getifname | sed '1d' | cut -d\" -f2)
ifconfig -j 1 $ifn name ngeth0b

ifconfig ngeth0a inet 192.168.128.1/30 up
ifconfig -j 1 ngeth0b inet 192.168.128.2/30 up

ping 192.168.128.2
jexec demo ping 192.168.128.1

Lets clean all of that up now:

jail -r demo
ngctl shutdown ngeth0a:

Ok that is not showing off everything a wormhole can do but that is because I have a separate utility that makes using it easier
and I will add tests that use it once that review is up.

So there will be more! In particular we will be making this:

But until then please feel free to start looking at the code, particularly interested in knowing if there is a better way than pulling in ng_rmnode. Also HK_COLLAPSE should probably be with other flags. That's the non-standard bit I definitely want more knowledgeable folks to look at but I appreciate everything being looked at as even if this never gets merged I use it!

[dave_freedave.net]

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

[dave_freedave.net]

share/man/man4/ng_wormhole.4

1

@ziaee I didn't (yet) change the man page license but can this shrink down too?

If it is allowed, is it just:

.\" Copyright (c) 2025 David Marker <[e-mail]>
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"