                 Virtual PC for OS/2 Virtual Switch
                 ==================================


(C) 2001-2002 InnoTek Systemberatung GmbH


1. Overview
-----------

Virtual PC for OS/2 allows you to execute additional operating
systems on top of your OS/2 system. Virtual PC provides access to
your system through virtual hardware making it a very flexible and
powerful solution.

Virtual Switch Networking is the most powerful way of connecting
your guest systems to an Ethernet network. It assigns a unique
MAC address to your virtual machine, allowing it to use arbitrary
network protocols and even act as a server. For other machine in
the network, the virtual machine appears as an additional network
station and it is indistinguishable from a "real" PC.

Note that while Virtual Switch Networking gives you more power
and flexibility, it also means additional administration. The
virtual machine uses a MAC address of its own and therefore needs
a unique IP address etc. For typical TCP/IP requirements, the
Shared Networking (NAT) is recommended.

1.1 Technical Background
------------------------

The Virtual Switch driver works by hooking between a physical
Ethernet card driver and software protocols such as TCP/IP,
IEEE 802.2 or NETBIOS. It switches the Ethernet card to the
so called "promiscuous mode". Normally, an Ethernet chip will
listen to all frames on the physical medium but only report
such frames that are either destined to its own MAC address
(UAA, universally administered address or LAA, locally
administered address), broadcast frames or multicast frames
matching the criteria stored by the protocol drivers in its
multicast table. All other frames will be ignored. In
promiscuous mode, the chip will pick up all frames, regardless
of where they are destined to. This is useful for network
traffic monitors and the Virtual Switch. The Virtual Switch
driver will get all frames from the Ethernet chip and first
look at the type of frame (unicast, multicast, broadcast).
For unicast frames, it will examine the destination MAC
address and see if it destined to any of the registered
virtual machines. For these frames and broadcast and
multicast frames, they will be passed on to Virtual PC.

The Virtual Switch driver also contains logic to allow a
virtual machine to communicate with another virtual machine
on the same host PC (again including full support for
broadcast and multicast frames) and to the host system
itself.

The Virtual Switch has been implemented in a way that causes
no impact on your host system's operation. Host system
networking will work like it did before. The Virtual Switch
will not cause any notable performance impact.
Also, the Virtual Switch will only put the Ethernet card
into promiscuous mode if there are one or more virtual
machines running.

It is "common knowledge" that promiscuous mode makes the
system slow. However, this is pretty much nonsense. First
of all, Virtual PC will only turn on promiscuous mode if
necessary and even when turned on, the performance hit is
so minimal that you will not notice any degradation. A
system that is capable of running Virtual PC is so fast,
that handling the additional frames on the Ethernet is not
a problem at all. A typical Ethernet is a switched Ethernet.
There, even in promiscuous mode, only frames destined to
the local system or systems connected to the same port of
the next switch can be found.


2. Prerequisites
----------------

2.1 Hardware
------------

OS/2 supported Ethernet card with a device driver capable of
operating it in promiscuous mode. Even though the Realtek 8139
OS/2 driver does not support promiscuous mode, the Virtual
Switch driver includes a special workaround to enable
promiscuous mode on this popular chipset.

Currently, only Ethernet cards (and other cards such as
WaveLAN 802.11b that use Ethernet frames) are supported. Token
Ring is not supported at this time as it is fundamentelly
different from Ethernet and not compatible with how the Virtual
Switch works. InnoTek is working on providing Token Ring support
in a future version of the product.

2.2 Software
------------

OS/2 Warp 4 with networking support (MPTS/LAPS) is required
for the Virtual Switch to operate.


3. Installation
---------------

3.1 Automatic Installation
--------------------------

During Virtual PC for OS/2 installation, you can also configure
Virtual Switch networking. The automatic installation will allow
you to attach the Virtual Switch to one network card (NIC) and
also allow you to uninstall the Virtual Switch at any time.

The Virtual Switch attaches to a given NIC. The installer will
present a list of NICs configured (read from PROTOCOL.INI with
NIC names taken from NIF files) and allow you to choose the card
the Virtual Switch will be attached to.

The installation program will automatically make the required
changes to CONFIG.SYS and PROTOCOL.INI. You can undo those changes
at any time by opening the Virtual PC setup program from the
Virtual PC folder and removing the Virtual Switch.

3.2 Manual Installation
-----------------------

Currently, advanced setup options for Virtual Switch networking
have to be done manually in MPTS. Usually, the automatic
installation is sufficient.

Before installation, please make a backup copy of
\IBMCOM\PROTOCOL.INI.

Open MPTS either through the program object in the system setup
folder or launching mpts.exe.

Go to the networking configuration screen. This screen contains
3 listboxes and a number of buttons. The upper left listbox contains
the list of registered MAC drivers (media access control, NDIS driver
for network cards). Click on "Other adapters..." and select the
Virtual Switch directory. This will add an additional network card
called "InnoTek Virtual Switch MAC" to the list.

The upper right listbox contains a list of registered NDIS protocol
drivers. Click on the "Other protocols..." button and select the
Virtual Switch directory. This will add a new protocol called
"InnoTek Virtual Switch Protocol" to the list.

The lower listbox contains the current configuration. It will
show the MAC drivers and the protocols bound to each MAC driver.
Assuming you have an IBM 10/100 PCI Ethernet card and use TCP/IP
as well as NETBIOS over TCP/IP, it will look as following:

IBM 10/100 Ethernet PCI Adapter...........
     0 - IBM TCP/IP
     0 - IBM OS/2 NETBIOS OVER TCP/IP

The Virtual Switch operates by hooking between the protocol
drivers and the MAC driver. In order to do this, you have to
carefully change the binding as follows.

Select the MAC driver you want to install the Virtual Switch
for (for instructions on how to support multiple MACs read the
following section after following the procedures described
here).

Now select the "InnoTek Virtual Switch MAC" in the upper left
listbox and press the "Change" button. Confirm the following
message. This will cause your protocols to be bound to the
Virtual Switch driver.

Now select your original MAC in the upper left listbox and click
add. It will appear in the lower list. Select the entry in this
list.

Now select the "InnoTek Virtual Switch Protocol" in the upper
right listbox and click "Add". For the IBM PCI card, your
bindings will now look as follows:

InnoTek Virtual Switch MAC...........
     0 - IBM TCP/IP
     0 - IBM OS/2 NETBIOS OVER TCP/IP

IBM 10/100 Ethernet PCI Adapter...........
     0 - InnoTek Virtual Switch Protocol

Save your changes in MPTS and when exiting, allow MPTS to change
your CONFIG.SYS. It will make a backup copy first and then install
the Virtual Switch driver (switch.os2).

NOTE: Due to a problem, you might have to manually copy vswch1.msg
from this archive to \IBMCOM. If the file does not exist after the
steps above, please copy it manually.

3.1.1 Multiple Ethernet cards
-----------------------------

In order to support more than one Ethernet card with the Virtual
Switch driver, you have change the bindings for each card like
described in the last section. However, you have to add the  MAC
and Protocol drivers from the "AdditionalDrivers" first to the
upper left and upper right listboxes. They will then appear
as "InnoTek Virtual Switch MAC 2" to "InnoTek Virtual Switch MAC 4"
and "InnoTek Virtual Switch Protocol 2" to
"InnoTek Virtual Switch Protocol 4".

They allow up to 4 Ethernet cards to use the Virtual Switch. This
is due to the OS/2 limit of 8 MAC drivers. As for each physical
MAC driver, the Virtual Switch MAC driver has to be installed,
only 4 Ethernet cards can be supported.

Note that you always use the appropriate MAC and Protocol driver.
The order does not matter, you just have to make sure that if you
use e.g. the MAC 3 driver for the original protocols, you have to
bind the Protocol 3 driver to the original MAC.

Be very careful with the setup and make sure the bindings are
correct - otherwise you will experience problems!


4. Configuration
----------------

Typically, the Virtual Switch does not need any configuration other
than the intial install described above. There are a few options
that are helpful in some configurations.

The Virtual Switch will report a name of the Ethernet card to the
Virtual PC application. The name will be taken from the PROTOCOL.INI
NIF section. Usually this is not a pretty or even recognizable name.
Therefore it is possible to assign a better name to a card by
defining the "Adaptername" setting for the Virtual Switch MAC driver.
To do so, just click on "Edit" below the lower listbox after
selecting the appropriate InnoTek Virtual Switch MAC driver.

For system equipped with a Realtek 8139 100MBit PCI Ethernet card,
a special workaround exists to enable promiscuous mode. This is
required in order to communicate with external systems. The
Realtek drivers for OS/2 all handle promiscuous mode
incorrectly. As this is a very popular chipset, we have decided
to provide a workaround. It is enabled by setting the
"Realtek 8139" property of the Virtual Switch MAC driver to
"YES". Choose "Edit" after selecting the appropriate Virtual
Switch MAC driver line in the lower listbox.


5. RAS
------

In order to diagnose the Virtual Switch operation, you can have a
look at the LANTRAN.LOG file. This can be viewed by issueing

type lantran.log

in an OS/2 command window. The Virtual Switch will output different
messages into this file. It will give you information about the
installed switching, bindings including sucess and error messages.

Also, it will show when virtual machines using the Virtual Switch
are started and stopped including the MAC address used for them.


6. Copyrights
-------------

(C) 2001-2002 InnoTek(R) Systemberatung GmbH
http://www.innotek.de

2002-03-31
