Added CMake support with managed protocol settings
[6bed4] / USAGE-NATIVE-64.MD
1 # Using 6bed4router under a Native /64 Prefix
2
3 > *Your ISP gave you a natively routed /64 prefix, and you want to use the
4 > 6bed4router as a tunnel.  The clients of that tunnel might be a mobile
5 > device or a home network.*
6
7 Following are instructions to setup for this.  We use the Linux command line
8 because it is the most general.  Your distribution may have clever ways of
9 automating the configuration, perhaps even graphically.  If you desire such
10 instructions, please use a forum for your distribution.
11
12
13 ## Assumptions
14
15 We assume that your hosting provider gave you a Linux virtual machine with
16 root privileges.  We assume that its primary network interface is named
17 `eth0` with MAC address `a8:bb:cc:00:11:22`.  The IPv6 prefix awarded to
18 you will be assumed to be `2001:db8:9:10::/64`.
19
20 When your `eth0` interface goes up, it automatically configures a link-local
21 address, meant for communication on the link (to the router of your hosting
22 provider).  It will start fall under `fe80::/10` and in this case should be
23 `fe80::aabb:ccff:fe00:1122`.  You can see that it contains a mangled form
24 of the MAC address of the interface.
25
26 Without explicitly adding an IPv6 address with a global scope, you already
27 have this link-scoped address configured:
28
29 ```
30 shell# ip -6 addr show dev eth0
31 0: eth0: <...> ...
32     inet6 fe80::aabb:ccff:fe00:1122/64 scope link
33 ```
34
35 The upstream router could use `ping6` to reach you at this address, and so
36 could you from this virtual machine.  However, this being a link-scoped
37 address, nobody else could reach the IPv6 address.
38
39
40 ## Example Setup
41
42 First, the IPv6 default route is set to the address of the upstream router
43 of the hosting provider, something like
44
45 ```
46 shell$ ip -6 route add default via fe80::aabb:ccff:fedd:eeff dev eth0
47 shell$ ip -6 route show
48 default via fe80::aabb:ccff:fedd:eeff dev eth0 metric 1024 mtu 1500 ...
49 ```
50
51 Most people configure their hosted machine like they would do with a
52 machine on their home network.  So, we shall add a few IPv6 addresses:
53
54 ```
55 shell# ip -6 addr add 2001:db8:9:10::11/64 dev eth0
56 shell# ip -6 addr add 2001:db8:9:10::30/64 dev eth0
57 shell# ip -6 addr show dev eth0
58 0: eth0: <...> ...
59     inet6 2001:db8:9:10::30/64 scope global
60     inet6 2001:db8:9:10::11/64 scope global
61     inet6 fe80::aabb:ccff:fe00:1122/64 scope link
62 ```
63
64 Note how the new addresses are setup with global scope.  Indeed, anyone on
65 the Internet should now be able to `ping6` you on that address.  You are
66 online!
67
68 You can now configure programs like a webserver to listen to one or both
69 of these addresses.  Inasfar as they are already listening to all addresses
70 they will immediately pickup on the newly added addresses.  This applies
71 to `ping6` but also to most installations of `sshd`:
72
73 ```
74 shell# netstat -ptnl6
75 9378/sshd   0   0   :::22   ...
76 ```
77
78 It would be confusing to parse due to the colon between the address and port,
79 but `:::22` indicates address `::` and port 22.  In other words, `sshd` with
80 pid 9378 listens to all addresses and will respond to the newly added IPv6
81 addresses.
82
83
84 ## Enter 6bed4router
85
86 When you are using `6bed4router`, chances are it's the first time you start
87 to think of your virtual host as a router.  This is indeed the added value of
88 the vast array of addresses that you get with IPv6.
89
90 The example setup sketched before is common, but from a router's viewpoint
91 it is flawed.  Just look at this:
92
93 ```
94 shell# ip -6 route show
95 2001:db8:9:10::/64 dev eth0 ...
96 fe80::/64 dev eth0 ...
97 default via fe80::aabb:ccff:fedd:eeff dev eth0 ...
98 ```
99
100 Note how silly this is &mdash; you are directing your assigned native /64
101 prefix back to the router of your hosting provider.  This is the result of
102 your use of a `/64` prefix when you setup your two addresses on `eth0`.
103
104 When your `eth0` is attached to a LAN, this setup makes sense; the LAN
105 has numerous hosts under this /64 prefix, and so your networking stack should
106 consider anything under the prefix local to the `eth0` link.  The prefix
107 is attached to the LAN by a router that connects the LAN to the rest of the
108 IPv6 internet.
109
110 In your hosting setup, this is usually not how things are done.  Here, the
111 `eth0` interface is a direct link to an upstream router whose sole purpose
112 it is to relay your prefix to your `eth0` interface.  There are no other
113 hosts residing under the same /64 prefix.  Still, as long as you enumerate
114 all actual IPv6 addresses in use on the `eth0` interface, this is going
115 to work.
116
117 But now you want to add `6bed4router`, which means you have entered the
118 realm of routing yourself.  Now what do you do?  If you let it, the
119 `6bed4router` creates a `6bed4` network interface with the same /64 prefix,
120 and your system might get confused.
121
122 The solution is simple.  You can use `eth0` for inbound traffic for your
123 /64 prefix, even when it does not have local addresses assigned.  All you
124 need to ensure is that it forwards frames that it cannot handle on the
125 interface itself.
126
127 ```
128 shell# sysctl -w net.ipv6.conf.eth0.ip_forwarding=1
129 shell# sysctl net.ipv6.conf.eth0.ip_forwarding
130 net.ipv6.conf.eth0.ip_forwarding = 1
131 ```
132
133 and, if you intend to support multicast as well, perhaps even
134
135 ```
136 shell# sysctl -w net.ipv6.conf.eth0.ip_mc_forwarding=1
137 shell# sysctl net.ipv6.conf.eth0.ip_mc_forwarding
138 net.ipv6.conf.eth0.ip_mc_forwarding = 1
139 ```
140
141 You could now remove the IPv6 addresses to pass all the traffic, for insance
142 to the 6bed4 interface, which is not desirable if you intend to run servers
143 under your /64 as well.  But this is how it would be done:
144
145 ```
146 shell# ip -6 addr del 2001:db8:9:10::11/64 dev eth0
147 shell# ip -6 addr del 2001:db8:9:10::30/64 dev eth0
148 shell# ip -6 addr show dev eth0
149 0: eth0: <...> ...
150     inet6 fe80::aabb:ccff:fe00:1122/64 scope link
151 shell# ip -6 route show
152 fe80::/64 dev eth0 ...
153 ```
154
155 The trick is to redefine the addresses with a longer prefix than /64.  With
156 the /64 assigned to the `6bed4` interface, the longer prefix is a better match
157 for some packets, which are then not forwarded over `6bed4`.
158
159 There is explicit support in the 6bed4 design for this approach, and that is
160 by being utterly uninterested in certain addresses.  The one-but-last word
161 in the address structure of 6bed4 represents an UDP port, and since port 0
162 is never permitted, there is a whole range of IPv6 addresses that can be
163 bypassed for other uses &mdash; such as running a server locally.  There just
164 have to take a format `xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:0000:xxxx` to be clearly
165 distinguishable from 6bed4 addresses.  In our case, we can use the addresses
166 ending in `::11` and `::30` without confusing with 6bed4.  A decent prefix
167 to use would be either /128 for an exact match with the address or, if we
168 wish to offload the routing tables, a /112 prefix that is certain to hold
169 at least the port number.
170
171 The next question is where the addresses should go.  For /128 prefixes, the
172 `eth0` interface would be quite good, so it can match the addresses locally
173 and refrain from further routing.  This is also pleasant if there is a
174 preference to route IPv4 and IPv6 over the same interfaces (though that is
175 a subject desire).  Aside from the already-coded removal of the old
176 addresses, the procedure would be:
177
178
179 ```
180 shell# ip -6 addr add 2001:db8:9:10::11/128 dev eth0
181 shell# ip -6 addr add 2001:db8:9:10::30/128 dev eth0
182 shell# ip -6 addr show dev eth0
183 0: eth0: <...> ...
184     inet6 2001:db8:9:10::30/128 scope global
185     inet6 2001:db8:9:10::11/128 scope global
186     inet6 fe80::aabb:ccff:fe00:1122/128 scope link
187 ```
188
189 Where the option of one or more /112 prefixes is preferred, we might instead
190 do that on `eth0`, or choose to not send packets for the smaller network
191 ranges back upstream by creating a virtual network interface.  It may be
192 helpful to create a "dummy" network interface, which holds your
193 local IPv6 addresses and has them routed through the loopback interface,
194
195 ```
196 shell# ip -6 link add dumbo0 type dummy
197 shell# ip -6 link set dumbo0 up
198 shell# ip -6 link show dev dumbo0
199 1: dumbo0: <...> ...
200     link/ether 11:22:33:44:55:66 brd ff:ff:ff:ff:ff:ff
201 ```
202
203 Variations on this are many...
204
205  1. You could create virtuel ethernet devices
206     to link directly to others, possibly in another
207     [networking name space](https://blog.scottlowe.org/2013/09/04/introducing-linux-network-namespaces/)
208     or [container](https://linuxcontainers.org), and so on.
209  2. You could setup a tunnel with a tool like
210     [socat](http://www.dest-unreach.org/socat/)
211     to relay traffic to another network, where you unleash the
212     address range via
213     [Router Advertisements](http://www.litech.org/radvd/) and
214     [DHCPv6](https://www.sixxs.net/wiki/Configuring_ISC_DHCPv6_Server).
215  3. You could setup a
216     [translation](http://openhip.sourceforge.net) to logical addresses using the
217     [Host Identity Protocol](https://en.wikipedia.org/wiki/Host_Identity_Protocol).
218  4. You could export an address range over a
219     [DNS tunnel](http://code.kryo.se/iodine/).
220  5. You could run [L2TP](http://openl2tp.org)
221     to connect networks based on the /112 IPv6 prefix, possibly
222     as a backend to PPPoE clients.  Add IPsec and you have a nice,
223     standards-compliant VPN.
224
225 And you could mix in any way you like, by assigning different /112
226 prefixes to each interface.  Given the port-0 assumption, you have 4294967296
227 of those ranges for a total of 281474976710656 hosts, we hope that you will
228 agree that 6bed4 leaves you some room to play.
229
230 Again, we should ensure forwarding:
231
232 ```
233 shell# sysctl -w net.ipv6.conf.eth0.ip_forwarding=1
234 shell# sysctl net.ipv6.conf.eth0.ip_forwarding
235 net.ipv6.conf.eth0.ip_forwarding = 1
236 ```
237
238 and possibly
239
240 ```
241 shell# sysctl -w net.ipv6.conf.eth0.ip_mc_forwarding=1
242 shell# sysctl net.ipv6.conf.eth0.ip_mc_forwarding
243 net.ipv6.conf.eth0.ip_mc_forwarding = 1
244 ```
245
246 Now we can proceed by adding the IPv6 addresses again, but this time with a
247 /112 prefix and to the `dumbo0` device:
248
249 ```
250 shell# ip -6 addr add 2001:db8:9:10::11/112 dev dumbo0
251 shell# ip -6 addr add 2001:db8:9:10::30/112 dev dumbo0
252 shell# ip -6 addr show dev dumbo0
253 0: dumbo0: <...> ...
254     inet6 fe80::aabb:ccff:fe00:1122/64 scope link
255     inet6 2001:db8:9:10::30/112 scope global
256     inet6 2001:db8:9:10::11/112 scope global
257 ```
258
259 Do not forget to remove the /64 prefixes from `eth0`, as coded above.
260
261 You can now run `6bed4router` without further problems.
262
263 ## Poorly Configured Upstreams
264
265 Now that you are running a router, you may be assuming that your uplink
266 does, too.  This may not always be true.  For instance:
267
268   * You may be running the `6bed4router` on an ethernet LAN
269   * Your upstream may not be configured with your link-local address
270     for your IPv6 range
271
272 In these cases, you may be subjected to Neighbor Solicitation requests
273 for the various IPv6 addresses that make up 6bed4.  This is a pitty, as
274 the variety of addresses may be a bit much for the upstream.  So if you
275 can, tell your upstream to do something like
276
277 ```
278 shell$ ip -6 route add 2001:db9:9:10::/64 via fe80::aa:bb:cc:ff:fe::dd:ee:ff/64 dev eth0
279 ```
280
281 If this is not an option, for instance because the router is managed
282 by another party that does not respond to such inquiries, you may have to
283 [Proxy Neighbor Discovery](https://github.com/DanielAdolfsson/ndppd/)
284 instead.  Once it runs, your connections should magically come alive.
285