GXemul  >  Documentation (



  Stable release (  




GXemul: Networking

Back to the index.


GXemul's current networking layer supports two modes:

  1. A NAT-like layer, which allows guest OSes to access the outside internet world (IPv4 only, so far). When only one machine is being emulated, the following default values apply to the guest OS:
    	IPv4 address:
    	Gateway / default route:
    To 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.

  2. A direct-access layer, allowing external tools to read/write raw ethernet packages from/to the emulator.

NOTE: Both these modes have problems. 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.) Because of the obvious limitations with the NAT approach, I have also included support for direct packet access, but this is not designed for security or anything like that.

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:

  • dec21143, Digital's 21143 PCI NIC (known as dc in OpenBSD, or tlp in NetBSD)
  • ether, the "fake" experimental ethernet device (documented here)
  • le, Turbochannel Lance Ethernet, as used in DECstation 5000/200 ("3max")
  • mec, the SGI O2's ethernet controller

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.

If you are impatient, and simply want to try out networking in GXemul, I would recommend trying out an ftp install of NetBSD/pmax.

Network across multiple hosts:

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 use configuration files, and the "direct-access" method of networking.

Although it is possible to have more than one machine per configuration file, I strongly recommend against it. Please use one configuration file for one emulated machine.

Here is a simple example:

!  Configuration file for a
!  "client" machine, netbooting
!  of another machine.

	name("client machine")
	serial_nr(1)	!

!  Configuration file for the
!  "server" machine.

	name("nfs server")
	serial_nr(2)	!


This example creates a network using the default settings (, 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 added with add_remote()).

As you can see in the example, this is a configuration file 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.

NOTE: There is no error checking or security checking of any kind. All UDP packets arriving at the input port are added to the emulated ethernet. This is not very good of course; use this feature at your own risk.

Direct-access example 1: udp_snoop:

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 looking something like this:



In addition to the machine section, you can see that there is also a net() section. It defaults to emulating a IPv4 NATed network, but there is also an additional "raw output", to UDP port 12300.

Now, do the following:

  • Start the emulator with the configuration file, i.e. gxemul @testconfig.
  • Start udp_snoop 12300 in another terminal.
  • Inside emulated NetBSD/pmax, type ifconfig le0

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                                ......