v86/docs/networking.md

v86 networking

Emulating a network card is supported. It can be used by passing the network_relay_url option to V86. The url must point to a running WebSockets Proxy. The source code for WebSockets Proxy can be found at benjamincburns/websockproxy. An alternative, Node-based implementation is krishenriksen/node-relay.

The network card could also be controlled programatically, but this is currently not exposed.

There is no built-in support for NodeJS, but networking only depends on a browser-compatible WebSocket constructor being present in the global scope.

NOTE: original benjamincburns/jor1k-relay:latest docker image has throttling built-in by default which will degrade the networking. bellenottelling/websockproxydocker image has this throttling removed via websockproxy/issues/4#issuecomment-317255890.

Interaction with state images

When using state images, v86 randomises the MAC address after the state has been loaded, so that multiple VMs don't receive the same address. However, the guest OS is not aware that the MAC address has changed, which prevents it from sending and receiving packets correctly. There are several workarounds:

• Unload the network driver before saving the state. On Linux, unloading can be done using rmmod ne2k-pci or echo 0000:00:05.0 > /sys/bus/pci/drivers/ne2k-pci/unbind and loading (after the state has been loaded) using modprobe ne2k-pci or echo 0000:00:05.0 > /sys/bus/pci/drivers/ne2k-pci/bind
• Pass preserve_mac_from_state_image: true to the V86 constructor. This causes MAC addresses to be shared between all VMs with the same state image.
• Pass mac_address_translation: true to the V86 constructor. This causes v86 to present the old MAC address to the guest OS, but translate it to a randomised MAC address in outgoing packets (and vice-versa for incoming packets). This mechanism currently only supports the ethernet, ipv4, dhcp and arp protcols. See translate_mac_address in src/ne2k.js. This is currently used in Windows, ReactOS and SerenityOS profiles.
• Some OSes don't cache the MAC address when the driver loads and therefore don't need any of the above workarounds. This seems to be the case for Haiku, OpenBSD and FreeBSD.

Note that the same applies to IP addresses, so a dhcp client should only be run after the state has been loaded.