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