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.

=head1 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 user space 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.

=head1 Interface Initialisation

Unless otherwise notes, the network interface will be initialized with the
expected 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.

=head1 Interface Types

=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/bsd

TAP-device, maybe; might work for many bsd variants.

This driver is a newer version of the C<tincd/*bsd> drivers. It I<might>
provide a TAP device, or might not work at all. You might try this
interface type first, and, if it doesn't work, try one of the OS-specific
drivers.

=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 untested 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
appropriate 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@schmorp.de>

Revision:	1.13
Committed:	Thu Oct 25 06:22:28 2018 UTC (5 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.12:	+1 -1 lines
Log Message:	* empty log message *
#	Content
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	=head1 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 user space 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	=head1 Interface Initialisation
34
35	Unless otherwise notes, the network interface will be initialized with the
36	expected 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	=head1 Interface Types
41
42	=head2 native/linux
43
44	TAP-device; already part of the kernel (only 2.4+ supported, but see
45	tincd/linux). This is the configuration tested best, as gvpe is being
46	developed on this platform.
47
48	C<ifname> should be set to the name of the network device.
49
50	To hardwire ARP addresses, use iproute2 (C<arp> can do it, too):
51
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	TAP-device; already part of the kernel (2.2 only). See
58	C<native/linux> for more info.
59
60	C<ifname> should be set to the path of a tap device,
61	e.g. C</dev/tap0>. The interface will be named accordingly.
62
63	=head2 native/cygwin
64
65	TAP-device; The TAP device to be used must either be the CIPE driver
66	(C<http://cipe-win32.sourceforge.net/>), or (highly recommended) the newer
67	TAP-Win32 driver bundled with openvpn (http://openvpn.sf.net/). Just
68	download and run the openvpn installer. The only option you need to select
69	is the TAP driver.
70
71	C<ifname> should be set to the name of the device, found in the registry
72	at (no kidding :):
73
74	HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\{4D36E972-E325-11CE-BFC1-08002BE10318}\<adapterid>\Connection\Name
75
76	The MAC address is dynamically being patched into packets and
77	ARP-requests, so only IPv4 works with ARP on this platform.
78
79	=head2 tincd/bsd
80
81	TAP-device, maybe; might work for many bsd variants.
82
83	This driver is a newer version of the C<tincd/*bsd> drivers. It I<might>
84	provide a TAP device, or might not work at all. You might try this
85	interface type first, and, if it doesn't work, try one of the OS-specific
86	drivers.
87
88	=head2 tincd/freebsd
89
90	TAP-device; part of the kernel (since 4.x, maybe earlier).
91
92	C<ifname> should be set to the path of a tap device,
93	e.g. C</dev/tap0>. The interface will be named accordingly.
94
95	These commands might be helpful examples:
96
97	ifconfig $IFNAME 10.0.0.$NODEID
98	route add -net 10.0.0.0 -netmask 255.255.255.0 -interface $IFNAME 10.0.0.$NODEID
99
100	=head2 tincd/netbsd
101
102	TUN-device; The interface is a point-to-point device. To initialize it,
103	you currently need to configure it as a point-to-point device, giving it
104	an address on your vpn (the exact address doesn't matter), like this:
105
106	ifconfig $IFNAME mtu $MTU up
107	ifconfig $IFNAME 10.11.12.13 10.55.66.77
108	route add -net 10.0.0.0 10.55.66.77 255.0.0.0
109	ping -c1 10.55.66.77 # ping once to tell gvpe your gw ip
110
111	The ping is required to tell the ARP emulator inside GVPE the local IP
112	address.
113
114	C<ifname> should be set to the path of a tun device,
115	e.g. C</dev/tun0>. The interface will be named accordingly.
116
117	=head2 tincd/openbsd
118
119	TUN-device; already part of the kernel. See C<tincd/netbsd> for more information.
120
121	=head2 native/darwin
122
123	TAP-device;
124
125	The necessary kernel extension can be found here:
126
127	http://www-user.rhrk.uni-kl.de/~nissler/tuntap/
128
129	There are two drivers, the one to use is the "tap" driver. It driver must
130	be loaded before use, read the docs on how to install it as a startup
131	item.
132
133	C<ifname> should be set to the path of a tap device,
134	e.g. C</dev/tap0>. The interface will be named accordingly.
135
136	These commands might be helpful examples:
137
138	ifconfig $IFNAME 10.0.0.$NODEID
139	route add -net 10.0.0.0 -interface $IFNAME 255.255.255.0
140
141	=head2 tincd/darwin
142
143	TUN-device; See C<tincd/netbsd> for more information. C<native/darwin> is
144	preferable.
145
146	The necessary kernel extension can be found here:
147
148	http://chrisp.de/en/projects/tunnel.html
149
150	C<ifname> should be set to the path of a tun device,
151	e.g. C</dev/tun0>. The interface will be named accordingly.
152
153	The driver must be loaded before use:
154
155	kmodload tunnel
156
157	=head2 tincd/solaris
158
159	TUN-device; already part of the kernel(?), or available here:
160
161	http://vtun.sourceforge.net/tun/
162
163	Some precompiled tun drivers might be available here:
164
165	http://www.monkey.org/~dugsong/fragroute/
166
167	The interface MAC and MTU are I<NOT> set up for you. Please try it out and
168	send me an C<ifconfig> command invocation that does that.
169
170	See C<tincd/netbsd> for more information.
171
172	Completely untested so far.
173
174	=head2 tincd/mingw
175
176	TAP-device; see C<native/cygwin> for more information.
177
178	The setup is likely to be similar to C<native/cygwin>.
179
180	Completely untested so far.
181
182	=head2 tincd/raw_socket
183
184	TAP-device; purpose unknown and untested, probably binds itself on an
185	existing ethernet device (given by C<ifname>). It must be down prior to
186	running the command, and GVPE will try to set it's MAC address and MTU to
187	the "correct" values.
188
189	Completely untested so far.
190
191	=head2 tincd/uml_socket
192
193	TAP-device; purpose unknown and untested, probably creates a UNIX datagram
194	socket (path given by C<ifname>) and reads and writes raw packets, so
195	might be useful in other than UML contexts.
196
197	No network interface is created, and the MAC and MTU must be set as
198	appropriate on the other side of the socket. GVPE will exit if the MAC
199	address doesn't match what it expects.
200
201	Completely untested so far.
202
203	=head2 tincd/cygwin
204
205	Known to be broken, use C<native/cygwin> instead.
206
207	=head1 SEE ALSO
208
209	gvpe(5).
210
211	=head1 AUTHOR
212
213	Marc Lehmann <gvpe@schmorp.de>
214