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

To configure the interface, use either iproute2:

  ip set $IFNAME address $MAC mtu $MTU up
  ip addr add $IFNAME 10.11.12.13
  ip route add $IFNAME 10.11.12.13/8

Or C<ifconfig>:

  ifconfig $IFNAME hw ether $MAC mtu $MTU
  ifconfig $IFNAME 10.11.12.13 netmask 255.0.0.0

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+ supported). See
C<native/linux> for more info.

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

The MAC need not be set (and in fact I<cannot> be set). 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). To initialize
the interface, use this command:

  ifconfig $IFNAME ether $MAC mtu $MTU up

=head2 tincd/netbsd

TUN-device; The interface is a point to point-device. To initialize it,
you currently need to configure it as such, 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

=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, using C<kmodload>.

=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

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/

See C<tincd/netbsd> for more information.

Completely unstested so far.

=head2 tincd/mingw

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

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>), which should probably not
be configured in any way, except for setting it I<up>.

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

=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.6
Committed:	Wed Mar 23 17:03:58 2005 UTC (19 years, 2 months ago) by pcg
Branch:	MAIN
Changes since 1.5:	+12 -7 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			=head2 native/linux
34
35	pcg	1.3	TAP-device; already part of the kernel (only 2.4+ supported, but see
36	pcg	1.1	tincd/linux). This is the configuration tested best, as gvpe is being
37			developed on this platform.
38
39			To configure the interface, use either iproute2:
40
41			ip set $IFNAME address $MAC mtu $MTU up
42			ip addr add $IFNAME 10.11.12.13
43			ip route add $IFNAME 10.11.12.13/8
44
45	pcg	1.4	Or C<ifconfig>:
46	pcg	1.1
47			ifconfig $IFNAME hw ether $MAC mtu $MTU
48			ifconfig $IFNAME 10.11.12.13 netmask 255.0.0.0
49
50	pcg	1.4	To hardwire ARP addresses, use iproute2 (C<arp> can do it, too):
51	pcg	1.1
52			MAC=fe:fd:80:00:00:$(printf "%02x" $NODEID)
53			ip neighbour add 10.11.12.13 lladdr $MAC nud permanent dev $IFNAME
54
55			=head2 tincd/linux
56
57	pcg	1.3	TAP-device; already part of the kernel (2.2+ supported). See
58			C<native/linux> for more info.
59	pcg	1.1
60			=head2 native/cygwin
61
62	pcg	1.3	TAP-device; The TAP device to be used must either be the CIPE driver
63			(C<http://cipe-win32.sourceforge.net/>), or (highly recommended) the newer
64			TAP-Win32 driver bundled with openvpn (http://openvpn.sf.net/). Just
65			download and run the openvpn installer. The only option you need to select
66			is the TAP driver.
67
68	pcg	1.4	The MAC need not be set (and in fact I<cannot> be set). The MAC address
69			is dynamically being patched into packets and ARP-requests, so only IPv4
70			works with ARP on this platform.
71	pcg	1.1
72			=head2 tincd/freebsd
73
74	pcg	1.3	TAP-device; part of the kernel (since 4.x, maybe earlier). To initialize
75			the interface, use this command:
76	pcg	1.1
77			ifconfig $IFNAME ether $MAC mtu $MTU up
78
79			=head2 tincd/netbsd
80
81	pcg	1.3	TUN-device; The interface is a point to point-device. To initialize it,
82	pcg	1.1	you currently need to configure it as such, giving it an address on your
83			vpn (the exact address doesn't matter), like this:
84
85			ifconfig $IFNAME mtu $MTU up
86			ifconfig $IFNAME 10.11.12.13 10.55.66.77
87			route add -net 10.0.0.0 10.55.66.77 255.0.0.0
88			ping -c1 10.55.66.77 # ping once to tell gvpe your gw ip
89
90			=head2 tincd/openbsd
91
92	pcg	1.3	TUN-device; already part of the kernel. See C<tincd/netbsd> for more information.
93	pcg	1.1
94	pcg	1.6	=head2 native/darwin
95	pcg	1.1
96	pcg	1.6	TAP-device;
97	pcg	1.1
98			The necessary kernel extension can be found here:
99
100	pcg	1.6	http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
101
102			There are two drivers, the one to use is the "tap" driver. It driver must
103			be loaded before use, using C<kmodload>.
104
105			=head2 tincd/darwin
106	pcg	1.1
107	pcg	1.6	TUN-device; See C<tincd/netbsd> for more information. C<native/darwin> is
108			preferable.
109	pcg	1.3
110	pcg	1.6	The necessary kernel extension can be found here:
111	pcg	1.3
112	pcg	1.6	http://chrisp.de/en/projects/tunnel.html
113	pcg	1.5
114			The driver must be loaded before use:
115
116			kmodload tunnel
117	pcg	1.3
118	pcg	1.1	=head2 tincd/solaris
119
120	pcg	1.5	TUN-device; already part of the kernel, or available here:
121
122			http://vtun.sourceforge.net/tun/
123
124			Some precompiled tun drivers might be available here:
125
126			http://www.monkey.org/~dugsong/fragroute/
127
128			See C<tincd/netbsd> for more information.
129
130			Completely unstested so far.
131	pcg	1.1
132			=head2 tincd/mingw
133
134	pcg	1.5	TAP-device; see C<native/cygwin> for more information.
135
136			Completely untested so far.
137
138			=head2 tincd/raw_socket
139
140			TAP-device; purpose unknown and untested, probably binds itself on an
141			existing ethernet device (given by C<ifname>), which should probably not
142			be configured in any way, except for setting it I<up>.
143
144			=head2 tincd/uml_socket
145
146			TAP-device; purpose unknown and untested, probably creates a unix datagram
147			socket (path given by C<ifname>) and reads and writes raw packets, so
148			might be useful in other than UML contexts.
149	pcg	1.1
150			=head2 tincd/cygwin
151
152	pcg	1.5	Known to be broken, use C<native/cygwin> instead.
153	pcg	1.1
154			=head1 SEE ALSO
155
156			gvpe(5).
157
158			=head1 AUTHOR
159
160			Marc Lehmann <gvpe@plan9.de>
161