usr.sbin/makefs: Add -o c|C option to specify comp|check type
[dragonfly.git] / share / examples / IPv6 / USAGE
blob3ca3c0fbb1ddf467bd56143f6f455ca0d1567777
1         USAGE
2         KAME Project
3         $KAME: USAGE,v 1.33 2000/11/22 10:22:57 itojun Exp $
4         $FreeBSD: src/share/examples/IPv6/USAGE,v 1.1.2.2 2001/07/03 11:01:24 ume Exp $
6 This is an introduction of how to use the commands provided in the KAME
7 kit.  For more information, please refer to each man page.
10 <<<ifconfig>>>
12 A link-local address is automatically assigned to each interface, when
13 the interface becomes up for the first time.  Even if you find an interface
14 without a link-local address, do not panic.  The link-local address will be
15 assigned when it becomes up (with "ifconfig IF up").
17 If you do not see a link-local address assigned to an interface on "ifconfig
18 up", the interface does not support IPv6 for some reasons - for example,
19 if the interface does not support link-layer multicast (IFF_MULTICAST is not
20 set), the interface cannot be used for IPv6.
22 Some network drivers allow an interface to become up even without a
23 hardware address (for example, PCMCIA network cards).  In such cases, it is
24 possible that an interface has no link-local address even if the
25 interface is up.  If you see such situation, please disable the
26 interface once and then re-enable it (i.e. do `ifconfig IF down;
27 ifconfig IF up').
29 Pseudo interfaces (like "gif" tunnel device) will borrow IPv6
30 interface identifier (lowermost 64bit of the address) from
31 EUI64/IEEE802 sources, like ethernet cards.  Pseudo interfaces will be
32 able to get an IPv6 link-local address, if you have other "real"
33 interface configured beforehand.  If you have no EUI64/IEEE802 sources
34 on the node, we have last-resort code in the kernel, which generates
35 interface identifier from MD5(hostname).  MD5(hostname) may not be suitable
36 for your usage (for example, if you configure same hostname on both sides of
37 gif tunnel, you will be doomed), and if so, you may need to configure
38 link-local address manually.
39 See RFC2472 for more discussion on how to generate an interface ID for
40 pseudo interfaces.
42 If you have a router announcing Router Advertisement,
43 global addresses will be assigned automatically.  So, neither
44 "ifconfig" nor "prefix" is necessary for your *host* (non-router node).
45 (Please refer to "sysctl" section for configuring a host to accept
46 Router Advertisement.)
48 If you want to set up a router, you need to assign global addresses
49 for two or more interfaces by "ifconfig" or "prefix" (prefix command
50 is described at next section).
51 If you want to assign a global address by "ifconfig", don't forget to
52 specify the "alias" argument to keep the link-local address.
54 # ifconfig de0 inet6 3ffe:501:808:1:200:f8ff:fe01:6317 prefixlen 64 alias
55 # ifconfig de0
56 de0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
57         inet6 fe80::200:f8ff:fe01:6317%de0 prefixlen 64 scopeid 0x1
58         inet 163.221.202.12 netmask 0xffffff00 broadcast 163.221.202.255
59         inet6 3ffe:501:808:1:200:f8ff:fe01:6317 prefixlen 64 
60         ether 00:00:f8:01:63:17 
61         media: 100baseTX status: active
63 See also "/etc/rc.network6" for actual examples.
65 <<prefix>>
67 In the IPv6 architecture, an IPv6 address of an interface can be
68 generated from a prefix assigned to the interface, and a
69 link-dependent identifier for the interface.  So assigning a full IPv6
70 address by ifconfig is not necessary anymore, because user can only
71 take care of prefix, by letting system take care of interface
72 identifier.
74 The newly added "prefix" command enables user to just assign prefixes
75 for interfaces, and let your system automatically generate IPv6
76 addresses.  Prefixes added by the "prefix" command is maintained in
77 the kernel consistently with prefixes assigned by Router
78 Advertisement (in case of hosts) and with prefixes assigned by Router
79 Renumbering (in case of routers).  Manual assignment of prefixes or
80 change of prefix properties take precedence over ones assigned by
81 Router Advertisement or Router Renumbering.
83 prefix command works only on routers.
85 If you want to assign a prefix (and consequently address) manually, do
86 as follows:
88 # ifconfig de0
89 de0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
90         inet6 fe80::200:f8ff:fe01:6317%de0 prefixlen 64 scopeid 0x1
91         inet 163.221.202.12 netmask 0xffffff00 broadcast 163.221.202.255
92         ether 00:00:f8:01:63:17 
93         media: 100baseTX status: active
94 # prefix de0 3ffe:501:808:1::
95 # ifconfig de0
96 de0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
97         inet6 fe80::200:f8ff:fe01:6317%de0 prefixlen 64 scopeid 0x1
98         inet 163.221.202.12 netmask 0xffffff00 broadcast 163.221.202.255
99         inet6 3ffe:501:808:1:200:f8ff:fe01:6317 prefixlen 64 
100         ether 00:00:f8:01:63:17 
101         media: 100baseTX status: active
103 To check assigned prefix, use the "ndp" command (See description of
104 ndp command about its usage).
106 # ndp -p
107 3ffe:501:808:1::/64 if=de0
108   flags=LA, vltime=2592000, pltime=604800, expire=Never, origin=RR
109   No advertising router
111 The "prefix" command also has node internal prefix renumbering
112 ability.
114 If you have multiple prefixes which have 3ffe:501:808:/48 at the top,
115 and would like to renumber them to 3ffe:501:4819:/48, then use the
116 "prefix" command with the "matchpr" argument and the "usepr" argument.
118 Suppose that current state of before renumbering as follows:
120 # ifconfig de0
121 de0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
122         inet6 fe80::200:f8ff:fe01:6317%de0 prefixlen 64 scopeid 0x1
123         inet 163.221.202.12 netmask 0xffffff00 broadcast 163.221.202.255
124         inet6 3ffe:501:808:1:200:f8ff:fe01:6317 prefixlen 64 
125         ether 00:00:f8:01:63:17 
126         media: 100baseTX status: active
127 # ifconfig de1
128 de1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
129         inet6 fe80::200:f8ff:fe55:7011%de1 prefixlen 64 scopeid 0x2
130         inet 163.221.203.12 netmask 0xffffff00 broadcast 163.221.203.255
131         inet6 3ffe:501:808:2:200:f8ff:fe55:7011 prefixlen 64 
132         ether 00:00:f8:55:70:11
133         media: 100baseTX status: active
134 # ndp -p
135 3ffe:501:808:1::/64 if=de0
136   flags=LA, vltime=2592000, pltime=604800, expire=Never, origin=RR
137   No advertising router
138 3ffe:501:808:2::/64 if=de1
139   flags=LA, vltime=2592000, pltime=604800, expire=Never, origin=RR
140   No advertising router
142 Then do as follows:
144 # prefix -a matchpr 3ffe:501:808:: mp_len 48 usepr 3ffe:501:4819:: up_uselen 48 change
146 If command is successful, prefixes and addresses will be renumbered as
147 follows.
149 # ifconfig de0
150 de0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
151         inet6 fe80::200:f8ff:fe01:6317%de0 prefixlen 64 scopeid 0x1
152         inet 163.221.202.12 netmask 0xffffff00 broadcast 163.221.202.255
153         inet6 3ffe:501:4819:1:200:f8ff:fe01:6317 prefixlen 64 
154         ether 00:00:f8:01:63:17 
155         media: 100baseTX status: active
156 # ifconfig de1
157 de1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
158         inet6 fe80::200:f8ff:fe55:7011%de0 prefixlen 64 scopeid 0x2
159         inet 163.221.203.12 netmask 0xffffff00 broadcast 163.221.203.255
160         inet6 3ffe:501:4819:2:200:f8ff:fe55:7011 prefixlen 64 
161         ether 00:00:f8:55:70:11
162         media: 100baseTX status: active
163 # ndp -p
164 3ffe:501:4819:1::/64 if=de0
165   flags=LA, vltime=2592000, pltime=604800, expire=Never, origin=RR
166   No advertising router
167 3ffe:501:4819:2::/64 if=de1
168   flags=LA, vltime=2592000, pltime=604800, expire=Never, origin=RR
169   No advertising router
171 See also "/etc/rc.network6" for actual examples.
174 <<<route>>>
176 If there is a router announcing Router Advertisement on a subnet,
177 you need not to add a default route for your host by hand
178 (Please refer to "sysctl" section to accept Router Advertisement).
180 If you want to add a default route manually, do like:
182 # route add -inet6 default fe80::200:a2ff:fe0e:7543%ed0
184 "default" means ::/0.  In other cases, if "prefixlen" is omitted, 64
185 is assumed for "prefixlen" to get along with the aggregatable address.
187 Note that, in IPv6, a link-local address should be used as gateway
188 ("fe80::200:a2ff:fe0e:7543%ed0" in the above).  If you use global addresses,
189 ICMPv6 redirect will not work properly.  Also note that we use a special form
190 of link-local address as gateway.  See Section 1.3 of IMPLEMENTATION for
191 more details.
192 For ease of configuration we recommend you to avoid static routes and run
193 a routing daemon (route6d for example) instead.
196 <<<ping6>>>
198 Reachability can be checked by "ping6".  This "ping6" allows multicast
199 for its argument.
201 % ping6 -n -I ed0 ff02::1
203 PING6(56=40+8+8 bytes) fe80::5254:ff:feda:cb7d --> ff02::1%ed0
204 56 bytes from fe80::5254:ff:feda:cb7d%lo0, icmp_seq=0 hlim=64 time=0.25 ms
205 56 bytes from fe80::2a0:c9ff:fe84:ed6c%ed0, icmp_seq=0 hlim=64 time=1.333 ms(DUP!)
206 56 bytes from fe80::5254:ff:feda:d161%ed0, icmp_seq=0 hlim=64 time=1.459 ms(DUP!)
207 56 bytes from fe80::260:97ff:fec2:80bf%ed0, icmp_seq=0 hlim=64 time=1.538 ms(DUP!)
208 56 bytes from 3ffe:501:4819:2000:5054:ff:fedb:aa46, icmp_seq=0 hlim=255 time=1.615 ms(DUP!)
211 <<<ping6 -w>>>
213 Name resolution is possible by ICMPv6 node information query message.
214 This is very convenient for link-local addresses whose host name cannot be
215 resolved by DNS.  Specify the "-w" option to "ping6".
217 % ping6 -n -I ed0 -w ff02::1
219 64 bytes from fe80::5254:ff:feda:cb7d%lo0: fto.kame.net
220 67 bytes from fe80::5254:ff:feda:d161%ed0: banana.kame.net
221 69 bytes from fe80::2a0:c9ff:fe84:ebd9%ed0: paradise.kame.net
222 66 bytes from fe80::260:8ff:fe8b:447f%ed0: taroh.kame.net
223 66 bytes from fe80::2a0:c9ff:fe84:ed6c%ed0: ayame.kame.net
224         
226 <<<traceroute6>>>
228 The route for a target host can be checked by "traceroute6".
230 % traceroute6 tokyo.v6.wide.ad.jp
232 traceroute to tokyo.v6.wide.ad.jp (3ffe:501:0:401:200:e8ff:fed5:8923), 30 hops max, 12 byte packets
233  1  nr60.v6.kame.net  1.239 ms  0.924 ms  0.908 ms
234  2  otemachi.v6.wide.ad.jp  28.953 ms  31.451 ms  26.567 ms
235  3  tokyo.v6.wide.ad.jp  26.549 ms  26.58 ms  26.186 ms
237 If the -l option is specified, both address and name are shown in each line.
238 % traceroute6 -l tokyo.v6.wide.ad.jp
240 traceroute to tokyo.v6.wide.ad.jp (3ffe:501:0:401:200:e8ff:fed5:8923), 30 hops max, 12 byte packets
241  1  nr60.v6.kame.net (3ffe:501:4819:2000:260:97ff:fec2:80bf)  1.23 ms  0.952 ms  0.92 ms
242  2  otemachi.v6.wide.ad.jp (3ffe:501:0:1802:260:97ff:feb6:7ff0)  27.345 ms  26.706 ms  26.563 ms
243  3  tokyo.v6.wide.ad.jp (3ffe:501:0:401:200:e8ff:fed5:8923)  26.329 ms  26.36 ms  28.63 ms
246 <<<ndp>>>
248 To display the current Neighbor cache, use "ndp":
250 % ndp -a
251 Neighbor                      Linklayer Address   Netif Expire    St Flgs Prbs
252 nr60.v6.kame.net              0:60:97:c2:80:bf      ed0  expired   S    R 
253 3ffe:501:4819:2000:2c0:cff:fe 0:c0:c:10:3a:53       ed0  permanent R      
254 paradise.v6.kame.net          52:54:0:dc:52:17      ed0  expired   S    R 
255 fe80::200:eff:fe49:f929%ed0   0:0:e:49:f9:29        ed0  expired   S    R 
256 fe80::200:86ff:fe05:80da%ed0  0:0:86:5:80:da        ed0  expired   S      
257 fe80::200:86ff:fe05:c2d8%ed0  0:0:86:5:c2:d8        ed0  9s        R      
259 To flush all of the NDP cache entries, execute the following as root.
261 # ndp -c
263 To display the prefix list:
265 % ndp -p
266 3ffe:501:4819:2000::/64 if=ed0
267   flags=LA, vltime=2592000, pltime=604800, expire=29d23h59m58s, origin=RA
268   advertised by
269     fe80::5254:ff:fedc:5217%ed0 (reachable)
270     fe80::260:97ff:fec2:80bf%ed0 (reachable)
271     fe80::200:eff:fe49:f929%ed0 (no neighbor state)
273 To display the default router list:
275 % ndp -r
276 fe80::260:97ff:fec2:80bf if=ed0, flags=, expire=29m55s
277 fe80::5254:ff:fedc:5217 if=ed0, flags=, expire=29m7s
278 fe80::200:eff:fe49:f929 if=ed0, flags=, expire=28m47s
281 <<<rtsol>>>
283 To generate a Router Solicitation message right now to get global
284 addresses, use "rtsol".
286 # ifconfig ef0
287 ef0: flags=8863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX,MULTICAST>
288         link type ether 0:a0:24:ab:83:9b mtu 1500 speed 10Mbps
289         media 10baseT status active
290         inet6 fe80::2a0:24ff:feab:839b%ef0 prefixlen 64 scopeid 0x2
291 # rtsol ef0
292 # ifconfig ef0
293 ef0: flags=8863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX,MULTICAST>
294         link type ether 0:a0:24:ab:83:9b mtu 1500 speed 10Mbps
295         media 10baseT status active
296         inet6 fe80::2a0:24ff:feab:839b%ef0 prefixlen 64 scopeid 0x2
297         inet6 3ffe:501:4819:2000:2a0:24ff:feab:839b prefixlen 64
300 <<<rtsold>>>
302 rtsold is a daemon version of rtsol.  If you run KAME IPv6 on a laptop
303 computer and frequently move with it, the daemon is useful since it watches
304 the interface and sends router solicitations when the status of the interface
305 changes.  Note, however, that the feature is disabled by default.  Please
306 add -m option when invocation of rtsold.
308 rtsold also supports multiple interfaces.  For example, you can
309 invoke the daemon as follows:
311 # rtsold -m ep0 cnw0
314 <<<netstat>>>
316 To see routing table:
317         
318 # netstat -nr
319 # netstat -nrl
320         long format with Ref and Use.  Note that bsdi4 does not support the
321         -l option.  You should use the -O option instead.
324 <<<sysctl>>>
326 If "net.inet6.ip6.accept_rtadv" is 1, Router Advertisement is
327 accepted.  This means that global addresses and default route are
328 automatically set up.  Otherwise, the announcement is rejected.  The
329 default value is 0.  To set "net.inet6.ip6.accept_rtadv" to 1, execute
330 as follows:
332 # sysctl -w net.inet6.ip6.accept_rtadv=1
335 <<<gifconfig>>>
337 "gif" interface enables you to perform IPv{4,6} over IPv{4,6}
338 protocol tunneling.  To use this interface, you must specify the
339 outer IPv{4,6} address by using gifconfig, like:
341 # gifconfig gif0 163.221.198.61 163.221.11.21
343 "ifconfig gif0" will configure the address pair used for inner
344 IPv{4,6} header.
346 It is not required to configure inner IPv{4,6} address pair.  If
347 you do not configure inner IPv{4,6} address pair, tunnel link is
348 considered as un-numbered link and the source address of inner
349 IPv{4,6} address pair will be borrowed from other interfaces.
351 The following example configures un-numbered IPv6-over-IPv4 tunnel:
352 # gifconfig gif0 10.0.0.1 10.0.0.1 netmask 255.255.255.0
354 The following example configures numbered IPv6-over-IPv4 tunnel:
355 # gifconfig gif0 10.0.0.1 10.0.0.1 netmask 255.255.255.0
356 # ifconfig gif0 inet6 3ffe:501:808:5::1 3ffe:501:808:5::2 prefixlen 64 alias
358 IPv6 spec allows you to use point-to-point link without global IPv6
359 address assigned to the interface.  Routing protocol (such as RIPng)
360 uses link-local addresses only.  If you are to configure IPv6-over-IPv4
361 tunnel, you need not to configure an address pair for inner IPv6
362 header.  We suggest you to use the former example (un-numbered
363 IPv6-over-IPv4 tunnel) to connect to 6bone for simplicity.
365 Note that it is so easy to make an infinite routing loop using gif
366 interface, if you configure a tunnel using the same protocol family
367 for inner and outer header (i.e. IPv4-over-IPv4).
369 Refer to gifconfig(8) for more details.
372 <<<6to4>>>
374 WARNING: malicious party can abuse 6to4 relay routers/sites, read through
375 internet draft draft-itojun-ipv6-transition-abuse-xx.txt before configuring it.
377 "stf" interface enables you to perform 6to4 IPv6-over-IPv4 encapsulation,
378 as documented in draft-ietf-ngtrans-6to4-06.txt.  See stf(4) for details.
381 <<<inetd>>>
383 Inetd supports AF_INET and AF_INET6 sockets, with IPsec policy
384 configuration support.
386 Refer to inetd(8) for more details.
389 <<<IPsec>>>
391 IPsec requires fairly complex configuration, so here we show transport
392 mode only.  http://www.kame.net/newsletter/ has more comprehensive
393 examples.
395 Let us setup security association to deploy a secure channel between
396 HOST A (10.2.3.4) and HOST B (10.6.7.8).  Here we show a little
397 complicated example.  From HOST A to HOST B, only old AH is used.
398 From HOST B to HOST A, new AH and new ESP are combined.
399   
400 Now we should choose algorithm to be used corresponding to "AH"/"new
401 AH"/"ESP"/"new ESP".  Please refer to the "setkey" man page to know
402 algorithm names.  Our choice is MD5 for AH, new-HMAC-SHA1 for new AH,
403 and new-DES-expIV with 8 byte IV for new ESP.
405 Key length highly depends on each algorithm.  For example, key
406 length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1,
407 and 8 for new-DES-expIV.  Now we choose "MYSECRETMYSECRET",
408 "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively.
410 OK, let us assign SPI (Security Parameter Index) for each protocol.
411 Please note that we need 3 SPIs for this secure channel since three
412 security headers are produced (one for from HOST A to HOST B, two for
413 from HOST B to HOST A).  Please also note that SPI MUST be greater
414 than or equal to 256.  We choose, 1000, 2000, and 3000, respectively.
417                  (1)
418         HOST A ------> HOST B
420         (1)PROTO=AH
421                 ALG=MD5(RFC1826)
422                 KEY=MYSECRETMYSECRET
423                 SPI=1000
425                  (2.1)
426         HOST A <------ HOST B
427                <------
428                  (2.2) 
430         (2.1)
431         PROTO=AH
432                 ALG=new-HMAC-SHA1(new AH)
433                 KEY=KAMEKAMEKAMEKAMEKAME
434                 SPI=2000
436         (2.2)
437         PROTO=ESP
438                 ALG=new-DES-expIV(new ESP)
439                         IV length = 8
440                 KEY=PASSWORD
441                 SPI=3000
443 Now, let us setup security association.  Execute "setkey" on both HOST
444 A and B:
446 # setkey -c
447 add 10.2.3.4 10.6.7.8 ah  1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ;
448 add 10.6.7.8 10.2.3.4 ah  2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ;
449 add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ;
452 Actually, IPsec communication doesn't process until security policy
453 entries will be defined.  In this case, you must setup each host.
455 At A:
456 # setkey -c
457 spdadd 10.2.3.4 10.6.7.8 any -P out ipsec
458         ah/transport/10.2.3.4-10.6.7.8/require ;
461 At B:
462 spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
463         esp/transport//require
464         ah/transport//require ;
467 To utilize the security associations installed into the kernel, you
468 must set the socket security level by using setsockopt().
469 This is per-application (or per-socket) security.  For example,
470 the "ping" command has the -P option with parameter to enable AH and/or ESP.
472 For example:
473 % ping -P "out ipsec \
474         ah/transport//use \
475         esp/tunnel/10.0.1.1-10.0.1.2/require" 10.0.2.2
477 If there are proper SAs, this policy specification causes ICMP packet
478 to be AH transport mode inner ESP tunnel mode like below.
480            HOST C -----------> GATEWAY D ----------> HOST E
481           10.0.1.1        10.0.1.2   10.0.2.1       10.0.2.2
482             | |                 |                    |
483             | ======= ESP =======                    |
484             ==================== AH ==================
487 <<<EDNS0>>>
489 EDNS0 is defined in RFC2671.  With EDNS0, the resolver library can tell DNS
490 server of its receiving buffer size, and permit DNS server to transmit large
491 reply packet.  EDNS0 is necessary to take advantage of larger minimum MTU
492 in IPv6.  KAME libinet6 includes resolver side support for EDNS0.
493 Server side support for EDNS0 is included in ISC BIND9.
495         query packet with EDNS0
496         tells receive buffer size
497 KAME box -----------------------------> BIND9 DNS server
498 KAME box <----------------------------- BIND9 DNS server
499         can transmit jumbo reply, since DNS server
500         knows receive buffer size of KAME box
502 How to play with it:
503 - prepare KAME box and BIND9 DNS server (can be a same node)
504 - add the following into /etc/resolv.conf on KAME box:
505         options edns0           <--- enables EDNS0
506         nameserver <IPv4 or v6 address of BIND9 box>
507 - run applications compiled with libinet6 (like /usr/local/v6/bin/telnet),
508   see EDNS0 packet fly on the wire by tcpdump or some other method.
510 Caveats:
511 - BIND 4/8 DNS server will choke with EDNS0 packet, so you must not
512   turn the option on if you have BIND 4/8 DNS server.  If you enable
513   "options edns0" against BIND 4/8 DNS server, you will never be able
514   to resolve names.
515 - If you use IPv6 UDP as DNS transport, path MTU discovery may
516   affect the traffic.  KAME box tries to fragment packet to 1280
517   bytes, however, BIND9 may not.
518 - Some of our platforms do not use our extended resolver code in libinet6.
519   See COVERAGE for detail.
522 <<Further readings>>
524 http://www.netbsd.org/Documentation/network/ipv6/
525         Even if you are on non-netbsd operating system, the URL should be
526         useful.
527 http://www.kame.net/
529                                                         <end of USAGE>