gvpe/doc/gvpe.osdep.5.pod

=head1 NAME

gvpe.osdep - os dependent information

=head1 DESCRIPTION

This file tries to capture OS-dependent configuration or build issues,
quirks and platform limitations, as known.

=head2 TUN vs. TAP interface

Most operating systems nowadays support something called a
I<tunnel>-device, which makes it possible to divert IPv4 (and often other
protocols, too) into a userspace daemon like C<gvpe>. This is being
referred to as a TUN-device.

This is fine for point-to-point tunnels, but for a virtual ethernet, an
additional ethernet header is needed. This functionality (called a TAP
device here) is only provided by a subset of the configurations.

On platforms only supporting a TUN-device, gvpe will invoke it's magical
ethernet emulation package, which currently only handles ARP requests for
the IPv4 protocol (but more could be added, bu the tincd network drivers
might need to be modified for this to work). This means that on those
platforms, only IPv4 will be supported.

Also, since there is no way (currently) to tell gvpe which IP subnets are
found on a specific host, you will either need to hardwire the MAC address
for TUN-style hosts on all networks (and avoid ARP altogether, which is
possible), or you need to send a packet from these hosts into the vpn
network to tell gvpe the local interface address.

=head2 Interface Initialisation

Unless otherwise notes, the network interface will be set "UP" with the
correct MAC address and correct MTU value. With most interface drivers,
this is done by running C</sbin/ifconfig>, so make sure that this command
exists.

=head2 native/linux

TAP-device; already part of the kernel (only 2.4+ supported, but see
tincd/linux). This is the configuration tested best, as gvpe is being
developed on this platform.

C<ifname> should be set to the name of the network device.

To hardwire ARP addresses, use iproute2 (C<arp> can do it, too):

  MAC=fe:fd:80:00:00:$(printf "%02x" $NODEID)
  ip neighbour add 10.11.12.13 lladdr $MAC nud permanent dev $IFNAME

=head2 tincd/linux

TAP-device; already part of the kernel (2.2 only). See
C<native/linux> for more info.

C<ifname> should be set to the path of a tap device,
e.g. C</dev/tap0>. The interface will be named accordingly.

=head2 native/cygwin

TAP-device; The TAP device to be used must either be the CIPE driver
(C<http://cipe-win32.sourceforge.net/>), or (highly recommended) the newer
TAP-Win32 driver bundled with openvpn (http://openvpn.sf.net/). Just
download and run the openvpn installer. The only option you need to select
is the TAP driver.

C<ifname> should be set to the name of the device, found in the registry
at (no kidding :):

      HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\{4D36E972-E325-11CE-BFC1-08002BE10318}\<adapterid>\Connection\Name

The MAC address is dynamically being patched into packets and
ARP-requests, so only IPv4 works with ARP on this platform.

=head2 tincd/freebsd

TAP-device; part of the kernel (since 4.x, maybe earlier).

C<ifname> should be set to the path of a tap device,
e.g. C</dev/tap0>. The interface will be named accordingly.

These commands might be helpful examples:

  ifconfig $IFNAME 10.0.0.$NODEID
  route add -net 10.0.0.0 -netmask 255.255.255.0 -interface $IFNAME 10.0.0.$NODEID

=head2 tincd/netbsd

TUN-device; The interface is a point-to-point device. To initialize it,
you currently need to configure it as a point-to-point device, giving it
an address on your vpn (the exact address doesn't matter), like this:

  ifconfig $IFNAME mtu $MTU up
  ifconfig $IFNAME 10.11.12.13 10.55.66.77
  route add -net 10.0.0.0 10.55.66.77 255.0.0.0
  ping -c1 10.55.66.77 # ping once to tell gvpe your gw ip

The ping is required to tell the ARP emulator inside GVPE the local IP
address.

C<ifname> should be set to the path of a tun device,
e.g. C</dev/tun0>. The interface will be named accordingly.

=head2 tincd/openbsd

TUN-device; already part of the kernel. See C<tincd/netbsd> for more information.

=head2 native/darwin

TAP-device;

The necessary kernel extension can be found here:

  http://www-user.rhrk.uni-kl.de/~nissler/tuntap/

There are two drivers, the one to use is the "tap" driver. It driver must
be loaded before use, read the docs on how to install it as a startup
item.

C<ifname> should be set to the path of a tap device,
e.g. C</dev/tap0>. The interface will be named accordingly.

These commands might be helpful examples:

  ifconfig $IFNAME 10.0.0.$NODEID
  route add -net 10.0.0.0 -interface $IFNAME 255.255.255.0

=head2 tincd/darwin

TUN-device; See C<tincd/netbsd> for more information. C<native/darwin> is
preferable.

The necessary kernel extension can be found here:

  http://chrisp.de/en/projects/tunnel.html

C<ifname> should be set to the path of a tun device,
e.g. C</dev/tun0>. The interface will be named accordingly.

The driver must be loaded before use:

  kmodload tunnel

=head2 tincd/solaris

TUN-device; already part of the kernel(?), or available here:

  http://vtun.sourceforge.net/tun/

Some precompiled tun drivers might be available here:

  http://www.monkey.org/~dugsong/fragroute/

The interface MAC and MTU are I<NOT> set up for you. Please try it out and
send me an C<ifconfig> command invocation that does that.

See C<tincd/netbsd> for more information.

Completely unstested so far.

=head2 tincd/mingw

TAP-device; see C<native/cygwin> for more information.

The setup is likely to be similar to C<native/cygwin>.

Completely untested so far.

=head2 tincd/raw_socket

TAP-device; purpose unknown and untested, probably binds itself on an
existing ethernet device (given by C<ifname>). It must be down prior to
running the command, and GVPE will try to set it's MAC address and MTU to
the "correct" values.

Completely untested so far.

=head2 tincd/uml_socket

TAP-device; purpose unknown and untested, probably creates a unix datagram
socket (path given by C<ifname>) and reads and writes raw packets, so
might be useful in other than UML contexts.

No network interface is created, and the MAC and MTU must be set as
approriate on the other side of the socket.  GVPE will exit if the MAC
address doesn't match what it expects.

Completely untested so far.

=head2 tincd/cygwin

Known to be broken, use C<native/cygwin> instead.

=head1 SEE ALSO

gvpe(5).

=head1 AUTHOR

Marc Lehmann <gvpe@plan9.de>

Revision:	1.8
Committed:	Wed Mar 23 21:55:39 2005 UTC (19 years, 2 months ago) by pcg
Branch:	MAIN
Changes since 1.7:	+52 -25 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	pcg	1.1	=head1 NAME
2
3			gvpe.osdep - os dependent information
4
5			=head1 DESCRIPTION
6
7			This file tries to capture OS-dependent configuration or build issues,
8			quirks and platform limitations, as known.
9
10			=head2 TUN vs. TAP interface
11
12			Most operating systems nowadays support something called a
13			I<tunnel>-device, which makes it possible to divert IPv4 (and often other
14			protocols, too) into a userspace daemon like C<gvpe>. This is being
15			referred to as a TUN-device.
16
17			This is fine for point-to-point tunnels, but for a virtual ethernet, an
18			additional ethernet header is needed. This functionality (called a TAP
19			device here) is only provided by a subset of the configurations.
20
21			On platforms only supporting a TUN-device, gvpe will invoke it's magical
22			ethernet emulation package, which currently only handles ARP requests for
23			the IPv4 protocol (but more could be added, bu the tincd network drivers
24			might need to be modified for this to work). This means that on those
25			platforms, only IPv4 will be supported.
26
27			Also, since there is no way (currently) to tell gvpe which IP subnets are
28			found on a specific host, you will either need to hardwire the MAC address
29			for TUN-style hosts on all networks (and avoid ARP altogether, which is
30			possible), or you need to send a packet from these hosts into the vpn
31			network to tell gvpe the local interface address.
32
33	pcg	1.8	=head2 Interface Initialisation
34
35			Unless otherwise notes, the network interface will be set "UP" with the
36			correct MAC address and correct MTU value. With most interface drivers,
37			this is done by running C</sbin/ifconfig>, so make sure that this command
38			exists.
39
40	pcg	1.1	=head2 native/linux
41
42	pcg	1.3	TAP-device; already part of the kernel (only 2.4+ supported, but see
43	pcg	1.1	tincd/linux). This is the configuration tested best, as gvpe is being
44			developed on this platform.
45
46	pcg	1.8	C<ifname> should be set to the name of the network device.
47	pcg	1.1
48	pcg	1.4	To hardwire ARP addresses, use iproute2 (C<arp> can do it, too):
49	pcg	1.1
50			MAC=fe:fd:80:00:00:$(printf "%02x" $NODEID)
51			ip neighbour add 10.11.12.13 lladdr $MAC nud permanent dev $IFNAME
52
53			=head2 tincd/linux
54
55	pcg	1.8	TAP-device; already part of the kernel (2.2 only). See
56	pcg	1.3	C<native/linux> for more info.
57	pcg	1.1
58	pcg	1.8	C<ifname> should be set to the path of a tap device,
59			e.g. C</dev/tap0>. The interface will be named accordingly.
60
61	pcg	1.1	=head2 native/cygwin
62
63	pcg	1.3	TAP-device; The TAP device to be used must either be the CIPE driver
64			(C<http://cipe-win32.sourceforge.net/>), or (highly recommended) the newer
65			TAP-Win32 driver bundled with openvpn (http://openvpn.sf.net/). Just
66			download and run the openvpn installer. The only option you need to select
67			is the TAP driver.
68
69	pcg	1.8	C<ifname> should be set to the name of the device, found in the registry
70			at (no kidding :):
71
72			HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\{4D36E972-E325-11CE-BFC1-08002BE10318}\<adapterid>\Connection\Name
73
74			The MAC address is dynamically being patched into packets and
75			ARP-requests, so only IPv4 works with ARP on this platform.
76	pcg	1.1
77			=head2 tincd/freebsd
78
79	pcg	1.8	TAP-device; part of the kernel (since 4.x, maybe earlier).
80	pcg	1.1
81	pcg	1.8	C<ifname> should be set to the path of a tap device,
82			e.g. C</dev/tap0>. The interface will be named accordingly.
83	pcg	1.1
84	pcg	1.7	These commands might be helpful examples:
85
86			ifconfig $IFNAME 10.0.0.$NODEID
87			route add -net 10.0.0.0 -netmask 255.255.255.0 -interface $IFNAME 10.0.0.$NODEID
88
89	pcg	1.1	=head2 tincd/netbsd
90
91	pcg	1.8	TUN-device; The interface is a point-to-point device. To initialize it,
92			you currently need to configure it as a point-to-point device, giving it
93			an address on your vpn (the exact address doesn't matter), like this:
94	pcg	1.1
95			ifconfig $IFNAME mtu $MTU up
96			ifconfig $IFNAME 10.11.12.13 10.55.66.77
97			route add -net 10.0.0.0 10.55.66.77 255.0.0.0
98			ping -c1 10.55.66.77 # ping once to tell gvpe your gw ip
99
100	pcg	1.8	The ping is required to tell the ARP emulator inside GVPE the local IP
101			address.
102
103			C<ifname> should be set to the path of a tun device,
104			e.g. C</dev/tun0>. The interface will be named accordingly.
105
106	pcg	1.1	=head2 tincd/openbsd
107
108	pcg	1.3	TUN-device; already part of the kernel. See C<tincd/netbsd> for more information.
109	pcg	1.1
110	pcg	1.6	=head2 native/darwin
111	pcg	1.1
112	pcg	1.6	TAP-device;
113	pcg	1.1
114			The necessary kernel extension can be found here:
115
116	pcg	1.6	http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
117
118			There are two drivers, the one to use is the "tap" driver. It driver must
119	pcg	1.7	be loaded before use, read the docs on how to install it as a startup
120			item.
121
122	pcg	1.8	C<ifname> should be set to the path of a tap device,
123			e.g. C</dev/tap0>. The interface will be named accordingly.
124	pcg	1.7
125			These commands might be helpful examples:
126
127			ifconfig $IFNAME 10.0.0.$NODEID
128			route add -net 10.0.0.0 -interface $IFNAME 255.255.255.0
129	pcg	1.6
130			=head2 tincd/darwin
131	pcg	1.1
132	pcg	1.6	TUN-device; See C<tincd/netbsd> for more information. C<native/darwin> is
133			preferable.
134	pcg	1.3
135	pcg	1.6	The necessary kernel extension can be found here:
136	pcg	1.3
137	pcg	1.6	http://chrisp.de/en/projects/tunnel.html
138	pcg	1.5
139	pcg	1.8	C<ifname> should be set to the path of a tun device,
140			e.g. C</dev/tun0>. The interface will be named accordingly.
141
142	pcg	1.5	The driver must be loaded before use:
143
144			kmodload tunnel
145	pcg	1.3
146	pcg	1.1	=head2 tincd/solaris
147
148	pcg	1.7	TUN-device; already part of the kernel(?), or available here:
149	pcg	1.5
150			http://vtun.sourceforge.net/tun/
151
152			Some precompiled tun drivers might be available here:
153
154			http://www.monkey.org/~dugsong/fragroute/
155
156	pcg	1.8	The interface MAC and MTU are I<NOT> set up for you. Please try it out and
157			send me an C<ifconfig> command invocation that does that.
158
159	pcg	1.5	See C<tincd/netbsd> for more information.
160
161			Completely unstested so far.
162	pcg	1.1
163			=head2 tincd/mingw
164
165	pcg	1.5	TAP-device; see C<native/cygwin> for more information.
166
167	pcg	1.8	The setup is likely to be similar to C<native/cygwin>.
168
169	pcg	1.5	Completely untested so far.
170
171			=head2 tincd/raw_socket
172
173			TAP-device; purpose unknown and untested, probably binds itself on an
174	pcg	1.8	existing ethernet device (given by C<ifname>). It must be down prior to
175			running the command, and GVPE will try to set it's MAC address and MTU to
176			the "correct" values.
177
178			Completely untested so far.
179	pcg	1.5
180			=head2 tincd/uml_socket
181
182			TAP-device; purpose unknown and untested, probably creates a unix datagram
183			socket (path given by C<ifname>) and reads and writes raw packets, so
184			might be useful in other than UML contexts.
185	pcg	1.1
186	pcg	1.8	No network interface is created, and the MAC and MTU must be set as
187			approriate on the other side of the socket. GVPE will exit if the MAC
188			address doesn't match what it expects.
189
190			Completely untested so far.
191
192	pcg	1.1	=head2 tincd/cygwin
193
194	pcg	1.5	Known to be broken, use C<native/cygwin> instead.
195	pcg	1.1
196			=head1 SEE ALSO
197
198			gvpe(5).
199
200			=head1 AUTHOR
201
202			Marc Lehmann <gvpe@plan9.de>
203