GXemul's current networking layer supports three modes:
IPv4 address: 10.0.0.1 Netmask: 255.0.0.0 Gateway / default route: 10.0.0.254 Nameserver: 10.0.0.254To the outside world, it will seem as if the host is doing all the networking, since the emulator is just a normal user process on the host.
NOTES:
The tap device support was contributed by Jason Thorpe.
The NAT-like layer is very "hackish" and was only meant as a proof-of-concept, to see if networking like this would work with e.g. NetBSD as a guest OS. (If you are interested in the technical details, and the reasons why NAT networking is implemented this way, you might want to read the networking section in the technical documentation.)
The UDP mode is used to connect multiple instances of GXemul in an easy way, but it provides no security of any kind.
Use the networking features at your own risk.
The emulated machine must have a NIC (network interface card). Not all machines have this. At the moment, the following NICs are more or less working:
It is not possible to simply attach any of the supported NICs into any of the supported emulated machines. Some machines, for example, have a specific NIC in them, others may have a PCI bus where a PCI NIC can be used. This is very much machine-dependent, and implemented on a case-by-case basis.
If you are impatient, and simply want to try out networking in GXemul, I would recommend trying out an ftp install of NetBSD/pmax.
The simplest way to emulate a real Ethernet network is using a tap device. In this mode, the emulator disables the simulated NAT and direct-access machinery and internally treats all emulated NICs as if they are on a single Ethernet switch. In this mode, packets destined for the guest's specific MAC address as well as Ethernet multicast and broadcast packets are send to the individual guest instances. Individual NIC emulations may also apply their own multicast filtering; multicast filtering is implemented for the DEC 21143 and Lance NICs.
The tap interface on the host can be thought of as an upstream link on the virtual Ethernet switch. In addition to providing a "port" for the host, the tap interface can be bridged to a physical Ethernet port on the host, allowing the guests to access the host's connected LAN.
Networking services such as DHCP and DNS must be provided either by the host or by the host's connected LAN.
Support for the tap device was developed on NetBSD, but should also work on FreeBSD, OpenBSD, and Linux hosts.
The easiest way to enable tap device networking is to use the -L command line option, e.g.:
gxemul -e 3max -L /dev/tap0 -d nbsd_pmax.img
In a machine.json file, it is the tapdev network setting (Network, Tap device, in the configuration window):
{
"gxemul": 1,
"name": "guest machine",
"machine": { "type": "decstation", "model": "3max" },
"drives": [ { "file": "nbsd_pmax.img" } ],
"network": { "tapdev": "/dev/tap0" }
}
Before starting the emulator, you will need to create the tap interface on the host. Here is an example for NetBSD:
# ifconfig tap0 create up
If you wish to simply network the host and the guests together, then simply assign an IP address to the tap interface on the host:
# ifconfig tap0 10.0.0.254
You can now run a DHCP server on the host for the guests, or you can configure the guests manually.
If instead you would like to bridge to the host's connected LAN, Here is an example for NetBSD:
# ifconfig bridge0 create up # brconfig add tap0 add wm0
Each emulated machine must have a tap instance of its own, and machines must use bridged tap devices if they wish to communicate with each other as if on the same LAN.
(The section above is written by Jason Thorpe.)
The way to emulate a network of multiple emulated machines, whether they are actually running on the same physical host, or on multiple hosts, is to run one emulator per machine, each with a machine.json of its own, and the "direct-access" method of networking.
Here is a simple example, a client machine netbooting off another machine:
{
"gxemul": 1,
"name": "client machine",
"machine": { "type": "sgi", "model": "o2",
"serial_nr": 1 },
"boot": { "load": [ "netbsd-GENERIC32_IP3x.gz" ] },
"network": {
"local_port": 15000,
"remotes": [ "localhost:15001" ]
}
}
|
{
"gxemul": 1,
"name": "nfs server",
"machine": { "type": "decstation", "model": "3max",
"serial_nr": 2 },
"drives": [ { "file": "nbsd_pmax.img" } ],
"network": {
"local_port": 15001,
"remotes": [ "localhost:15000" ]
}
}
|
(The serial numbers make the machines' Ethernet addresses, and 10.0.0.1 and 10.0.0.2, different.)
This example creates a network using the default settings (10.0.0.0/8), but it also uses the direct-access networking mode to allow the network to be connected to other emulator instances. "local_port": 15000 means that anything coming in to UDP port 15000 on the host is added to the network. All ethernet packets on the network are also sent out to all other connected machines (those in remotes).
As you can see in the example, these are configuration files for netbooting a NetBSD/sgimips diskless machine, with a NetBSD/pmax machine acting as the nfs server. Note that the nfs server has ports 15000 and 15001 reversed, compared to the client!
"localhost" can be changed to the Internet hostname of a remote machine, to run the simulation across a physical network.
Each UDP datagram carries one raw Ethernet frame with no other header, which is also the format of the HECnet bridge, simh (attach xq udp:...), QEMU (-netdev dgram) and gobootd's bootbridge. Frames are sent from local_port, so peers that learn their peers from incoming frames can answer.
NOTE: In this raw mode there is no security checking of any kind. All UDP packets arriving at the input port are added to the emulated ethernet. Use L2TPv3 with a cookie (below) for anything but a trusted network.
L2TPv3: With l2tp enabled, frames are carried in static L2TPv3 over UDP (RFC 3931, Ethernet as in RFC 4719), as Linux's ip l2tp, QEMU's -netdev l2tpv3 and bootbridge -l2tp speak it, without the control connection:
"network": {
"local_port": 1701,
"remotes": [ "192.168.1.10:1701" ],
"l2tp": {
"enabled": true,
"session": 1, default 1, used in both directions
"cookie": "0x0123456789abcdef", 8 or 16 hex digits, or ""
"counter": true default true: L2-specific sublayer
}
}
|
Datagrams with another session ID or cookie are dropped (a warning is printed for the first one), so the cookie works as a password against anyone who cannot see the traffic. It is sent in clear, so across untrusted networks carry the UDP over WireGuard or an SSH tunnel. Both ends must agree on the session, the cookie and counter.
In both modes, a keepalive (an Ethernet loopback frame addressed to the first NIC itself) is sent to the remotes every minute, so that a bridge which learns its peers keeps sending broadcasts to an idle machine. Keepalives received are dropped.
Note that the simulated gateway (10.0.0.254 by default, with DHCP and NAT) is still active in this mode, and answers DHCP requests.
The most basic example of how the simple direct-access system works is a small program in the experiments/ directory, udp_snoop, which simply dumps incoming UDP packets to the terminal, in hex and ASCII.
The easiest way to test the example is to download a NetBSD/pmax INSTALL kernel, and start the emulator with a configuration file, testconfig.json, looking something like this:
{
"gxemul": 1,
"machine": { "type": "decstation", "model": "3max" },
"boot": { "load": [ "netbsd-INSTALL.gz" ] },
"network": { "remotes": [ "localhost:12300" ] }
}
The network defaults to emulating a 10.0.0.0/8 IPv4 NATed network, but there is also an additional "raw output", to UDP port 12300.
Now, do the following:
This should be enough to see broadcast messages from the guest OS which are not directed to the gateway. It might look like this:
$ ./udp_snoop 12300 ff ff ff ff ff ff 10 20 30 00 00 10 08 06 00 01 ....... 0....... 08 00 06 04 00 01 10 20 30 00 00 10 0a 00 00 02 ....... 0....... 00 00 00 00 00 00 0a 00 00 02 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 00 00 00 00 ............ 33 33 ff 00 00 10 10 20 30 00 00 10 86 dd 60 00 33..... 0.....`. 00 00 00 20 00 01 00 00 00 00 00 00 00 00 00 00 ... ............ 00 00 00 00 00 00 ff 02 00 00 00 00 00 00 00 00 ................ 00 01 ff 00 00 10 3a 00 01 00 05 02 00 00 83 00 ......:......... 80 83 00 00 00 00 ff 02 00 00 00 00 00 00 00 00 ................ 00 01 ff 00 00 10 ...... ...