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