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