From 023e69424527f48b5c8c98d9859c91b980ad615c Mon Sep 17 00:00:00 2001 From: cold-brewed <47337035+cold-brewed@users.noreply.github.com> Date: Mon, 19 Jun 2023 16:19:52 -0400 Subject: [PATCH] Networking updates: VDE and null driver (#24) * Add VDE and null driver to networking documentation * Update copyright year --------- Co-authored-by: cold-brewed --- conf.py | 2 +- hardware/network.rst | 129 +++++++++++++++++++++++++++++++++++++++++-- settings/network.rst | 10 +++- 3 files changed, 135 insertions(+), 6 deletions(-) diff --git a/conf.py b/conf.py index f65b846..88baf48 100644 --- a/conf.py +++ b/conf.py @@ -19,7 +19,7 @@ import sphinx_rtd_theme # -- Project information ----------------------------------------------------- project = '86Box' -copyright = '2020-2022, 86Box Project' +copyright = '2020-2023, 86Box Project' author = '86Box Project' diff --git a/hardware/network.rst b/hardware/network.rst index 4332076..b7835ff 100644 --- a/hardware/network.rst +++ b/hardware/network.rst @@ -1,7 +1,16 @@ Networking ========== -86Box supports two connection modes for the :doc:`emulated network cards <../settings/network>`. The specific details on these connection modes and network emulation as a whole are outlined on this page. +86Box supports different connection modes for the :doc:`emulated network cards <../settings/network>`. The specific details on these connection modes and network emulation as a whole are outlined on this page. + +Null Driver +----------- + +The default mode. Network cards will be available to the virtual machine but all packets sent by the emulated network card will be dropped by 86Box. + +The virtual NIC will be in a *cable disconnected* state at machine startup. + +.. note:: In this mode connecting the cable will have no impact on the card's ability to send packets. Network cards that support cable detection will still be able to determine link or cable connection status. SLiRP ----- @@ -17,7 +26,7 @@ The virtual router provides automatic IP configuration to the emulated machine t The host can be reached through IP address 10.0.\ *x*\ .2, while other devices on the host's network can be reached through their normal IP addresses. -.. note:: SLiRP is only capable of routing TCP and UDP traffic. Other protocols such as IPX and NetBEUI can only be used with :ref:`hardware/network:PCap` networking. +.. note:: SLiRP is only capable of routing TCP and UDP traffic. Other protocols such as IPX and NetBEUI can only be used with :ref:`hardware/network:PCap` or :ref:`hardware/network:VDE` networking. PCap ---- @@ -46,8 +55,120 @@ If you have an incompatible network connection on your host system (such as Wi-F * Port forwarding can be performed through the Virtual Network Editor's *NAT Settings*. -Advanced features ------------------ +VDE +--- + +VDE stands for `Virtual Distributed Ethernet `_. It works by creating a virtual ethernet switch on your computer. See the `VDE basics page `_ for a brief overview. + +.. note:: VDE is only supported on **macOS** and **Linux** hosts + +One of the core concepts of VDE is the *plug*. 86Box supports VDE by being able to *plug* the virtual machine into a virtual switch created by VDE. + +VDE functions as a layer 2 switch which allows non-TCP protocols such as IPX and NetBEUI. + +Installing VDE tools +^^^^^^^^^^^^^^^^^^^^ + +You will need to ensure the VDE tools are installed on your system. The tools are required to create the virtual switch that 86Box attaches to with a virtual cable. + +macOS +""""" + +VDE is available in homebrew for macOS: + +.. code-block:: shell + + brew install vde + +VDE is also available in macports: + +.. code-block:: shell + + port install vde2 + +Linux +""""" + +For debian and derivatives, VDE and some of the associated commands are split into various packages. You'll need to install the libraries along with the associated tools: + +.. code-block:: shell + + apt install libvdeplug2 vde-switch vde2 + +.. note:: Other distributions should have similar package names. + +Creating the virtual switch +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to use VDE with 86Box you must first create the virtual switch with ``vde_switch``. + +.. note:: ``vde_switch`` requires root privileges to *create* the switch. Applications will be able to connect to the switch with standard (non-root) permissions. + +.. code-block:: shell + + vde_switch --mode 666 --numports 8 --mgmt /tmp/vde.mgmt --mgmtmode 666 -s /tmp/vde.ctl + +This command: + +* Creates the *management* socket at ``/tmp/vde.mgmt`` +* Creates the *control* socket at ``/tmp/vde.ctl`` +* Sets the socket permissions to world read/write to allow non-privileged access +* Sets the number of ports to 8 + +If you'd like to run ``vde_switch`` in the background add the ``--daemon`` option to the command. + +The important part to note here is the control socket ``/tmp/vde.ctl``. This is the socket name we will provide to 86Box in the network configuration. + +.. note:: You can adjust the file paths or permissions as necessary. For more information on the various options see ``vde_switch -h``. + +Configuring 86Box to use VDE +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From the Machine settings in 86Box (*Tools -> Settings*) choose *Network*. In the network card section there will be a drop-down list next to *Mode*. Choose **VDE**. + +In the *VDE Socket* section you will need to supply the name of the control socket. Using the above command as an example, place ``/tmp/vde.ctl`` in the *VDE Socket* section. + +Once the settings are saved the virtual machine should be connected to the VDE switch. + +.. warning:: Make sure the network cable is connected! Click on the network icon in the status bar and ensure there is a check by *Connected*. + +VDE switch status +^^^^^^^^^^^^^^^^^ + +The ``vdeterm`` command can be used to view the status of the virtual switch. In order to use ``vdeterm`` you will need to supply the name of the *management* socket (not the *control* socket) that was specified when the switch was created. + +In the above example the command would be ``vdeterm /tmp/vde.mgmt``. + +The ``vdeterm`` command provides you with a command interface. Type ``help`` to view the available commands. + +One helpful command is ``port/allprint``. This will print the status of the in-use ports along with all active processes that are currently plugged into the virtual switch. Example: + +.. code-block:: + + vde[/tmp/vde.mgmt]: port/allprint + + Port 0001 untagged_vlan=0000 ACTIVE - Unnamed Allocatable + Current User: myusername Access Control: (User: NONE - Group: NONE) + -- endpoint ID 0003 module unix prog : 86Box virtual card user=myusername PID=12345 + Success + +.. note:: If you did not pass the ``--daemon`` flag to ``vde_switch`` you can just hit enter to enter a shell identical to ``vdeterm`` and execute the same commands. + +Other VDE features +^^^^^^^^^^^^^^^^^^ + +This documentation only covers the basics of VDE use. There are many additional features not covered here and left as an exercise to the reader. + +Some examples include: + +* Using ``vde_cryptcab`` to connect virtual switches across physical machines +* Bridging VDE switches with network interfaces to provide access to the internet or other networks +* Establishing communication with other software that natively supports VDE such as *qemu* and *virtualbox* +* Creating VLANs and assigning them to a port on the switch +* Creating access control policies and assigning them to a port on the switch + +Advanced networking features +---------------------------- The following advanced features can be accessed by directly editing the emulated machine's configuration file, which is ``86box.cfg`` by default. diff --git a/settings/network.rst b/settings/network.rst index af5b176..f7c5775 100644 --- a/settings/network.rst +++ b/settings/network.rst @@ -15,9 +15,10 @@ Mode Network emulation mode to use on this card. See :doc:`../hardware/network` for more information on these. -* **None:** disable networking. +* **Null Driver:** the emulated card is available to the guest but all packets are dropped. * **PCap:** connects directly to a host network adapter. Similar to the **Bridge** mode on other emulators and virtualizers. * **SLiRP:** creates a private network with a virtual router. Similar to the **NAT** mode on other emulators and virtualizers. +* **VDE:** attaches the system to a virtual switch created by :ref:`hardware/network:VDE`. Interface ^^^^^^^^^ @@ -36,3 +37,10 @@ Network card to emulate. Only cards supported by the machine's expansion buses w The *Configure* button opens a new window with settings specific to the selected network card, such as the I/O port and IRQ for ISA cards. The **[LPT] Parallel Port Internet Protocol** network adapter requires a **PLIP Network** device to be attached to a :ref:`parallel port `. + +VDE Socket +^^^^^^^^^^ + +The socket name specified when creating the VDE virtual switch. Only used in **VDE** mode. + +See the :ref:`hardware/network:VDE` section for more information. \ No newline at end of file