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