doc.go (7899B)
1 // Copyright 2013 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package ipv6 implements IP-level socket options for the Internet 6 // Protocol version 6. 7 // 8 // The package provides IP-level socket options that allow 9 // manipulation of IPv6 facilities. 10 // 11 // The IPv6 protocol is defined in RFC 8200. 12 // Socket interface extensions are defined in RFC 3493, RFC 3542 and 13 // RFC 3678. 14 // MLDv1 and MLDv2 are defined in RFC 2710 and RFC 3810. 15 // Source-specific multicast is defined in RFC 4607. 16 // 17 // On Darwin, this package requires OS X Mavericks version 10.9 or 18 // above, or equivalent. 19 // 20 // # Unicasting 21 // 22 // The options for unicasting are available for net.TCPConn, 23 // net.UDPConn and net.IPConn which are created as network connections 24 // that use the IPv6 transport. When a single TCP connection carrying 25 // a data flow of multiple packets needs to indicate the flow is 26 // important, Conn is used to set the traffic class field on the IPv6 27 // header for each packet. 28 // 29 // ln, err := net.Listen("tcp6", "[::]:1024") 30 // if err != nil { 31 // // error handling 32 // } 33 // defer ln.Close() 34 // for { 35 // c, err := ln.Accept() 36 // if err != nil { 37 // // error handling 38 // } 39 // go func(c net.Conn) { 40 // defer c.Close() 41 // 42 // The outgoing packets will be labeled DiffServ assured forwarding 43 // class 1 low drop precedence, known as AF11 packets. 44 // 45 // if err := ipv6.NewConn(c).SetTrafficClass(0x28); err != nil { 46 // // error handling 47 // } 48 // if _, err := c.Write(data); err != nil { 49 // // error handling 50 // } 51 // }(c) 52 // } 53 // 54 // # Multicasting 55 // 56 // The options for multicasting are available for net.UDPConn and 57 // net.IPConn which are created as network connections that use the 58 // IPv6 transport. A few network facilities must be prepared before 59 // you begin multicasting, at a minimum joining network interfaces and 60 // multicast groups. 61 // 62 // en0, err := net.InterfaceByName("en0") 63 // if err != nil { 64 // // error handling 65 // } 66 // en1, err := net.InterfaceByIndex(911) 67 // if err != nil { 68 // // error handling 69 // } 70 // group := net.ParseIP("ff02::114") 71 // 72 // First, an application listens to an appropriate address with an 73 // appropriate service port. 74 // 75 // c, err := net.ListenPacket("udp6", "[::]:1024") 76 // if err != nil { 77 // // error handling 78 // } 79 // defer c.Close() 80 // 81 // Second, the application joins multicast groups, starts listening to 82 // the groups on the specified network interfaces. Note that the 83 // service port for transport layer protocol does not matter with this 84 // operation as joining groups affects only network and link layer 85 // protocols, such as IPv6 and Ethernet. 86 // 87 // p := ipv6.NewPacketConn(c) 88 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil { 89 // // error handling 90 // } 91 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil { 92 // // error handling 93 // } 94 // 95 // The application might set per packet control message transmissions 96 // between the protocol stack within the kernel. When the application 97 // needs a destination address on an incoming packet, 98 // SetControlMessage of PacketConn is used to enable control message 99 // transmissions. 100 // 101 // if err := p.SetControlMessage(ipv6.FlagDst, true); err != nil { 102 // // error handling 103 // } 104 // 105 // The application could identify whether the received packets are 106 // of interest by using the control message that contains the 107 // destination address of the received packet. 108 // 109 // b := make([]byte, 1500) 110 // for { 111 // n, rcm, src, err := p.ReadFrom(b) 112 // if err != nil { 113 // // error handling 114 // } 115 // if rcm.Dst.IsMulticast() { 116 // if rcm.Dst.Equal(group) { 117 // // joined group, do something 118 // } else { 119 // // unknown group, discard 120 // continue 121 // } 122 // } 123 // 124 // The application can also send both unicast and multicast packets. 125 // 126 // p.SetTrafficClass(0x0) 127 // p.SetHopLimit(16) 128 // if _, err := p.WriteTo(data[:n], nil, src); err != nil { 129 // // error handling 130 // } 131 // dst := &net.UDPAddr{IP: group, Port: 1024} 132 // wcm := ipv6.ControlMessage{TrafficClass: 0xe0, HopLimit: 1} 133 // for _, ifi := range []*net.Interface{en0, en1} { 134 // wcm.IfIndex = ifi.Index 135 // if _, err := p.WriteTo(data[:n], &wcm, dst); err != nil { 136 // // error handling 137 // } 138 // } 139 // } 140 // 141 // # More multicasting 142 // 143 // An application that uses PacketConn may join multiple multicast 144 // groups. For example, a UDP listener with port 1024 might join two 145 // different groups across over two different network interfaces by 146 // using: 147 // 148 // c, err := net.ListenPacket("udp6", "[::]:1024") 149 // if err != nil { 150 // // error handling 151 // } 152 // defer c.Close() 153 // p := ipv6.NewPacketConn(c) 154 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::1:114")}); err != nil { 155 // // error handling 156 // } 157 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil { 158 // // error handling 159 // } 160 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil { 161 // // error handling 162 // } 163 // 164 // It is possible for multiple UDP listeners that listen on the same 165 // UDP port to join the same multicast group. The net package will 166 // provide a socket that listens to a wildcard address with reusable 167 // UDP port when an appropriate multicast address prefix is passed to 168 // the net.ListenPacket or net.ListenUDP. 169 // 170 // c1, err := net.ListenPacket("udp6", "[ff02::]:1024") 171 // if err != nil { 172 // // error handling 173 // } 174 // defer c1.Close() 175 // c2, err := net.ListenPacket("udp6", "[ff02::]:1024") 176 // if err != nil { 177 // // error handling 178 // } 179 // defer c2.Close() 180 // p1 := ipv6.NewPacketConn(c1) 181 // if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil { 182 // // error handling 183 // } 184 // p2 := ipv6.NewPacketConn(c2) 185 // if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil { 186 // // error handling 187 // } 188 // 189 // Also it is possible for the application to leave or rejoin a 190 // multicast group on the network interface. 191 // 192 // if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil { 193 // // error handling 194 // } 195 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil { 196 // // error handling 197 // } 198 // 199 // # Source-specific multicasting 200 // 201 // An application that uses PacketConn on MLDv2 supported platform is 202 // able to join source-specific multicast groups. 203 // The application may use JoinSourceSpecificGroup and 204 // LeaveSourceSpecificGroup for the operation known as "include" mode, 205 // 206 // ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")} 207 // ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")} 208 // if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 209 // // error handling 210 // } 211 // if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil { 212 // // error handling 213 // } 214 // 215 // or JoinGroup, ExcludeSourceSpecificGroup, 216 // IncludeSourceSpecificGroup and LeaveGroup for the operation known 217 // as "exclude" mode. 218 // 219 // exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")} 220 // if err := p.JoinGroup(en0, &ssmgroup); err != nil { 221 // // error handling 222 // } 223 // if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil { 224 // // error handling 225 // } 226 // if err := p.LeaveGroup(en0, &ssmgroup); err != nil { 227 // // error handling 228 // } 229 // 230 // Note that it depends on each platform implementation what happens 231 // when an application which runs on MLDv2 unsupported platform uses 232 // JoinSourceSpecificGroup and LeaveSourceSpecificGroup. 233 // In general the platform tries to fall back to conversations using 234 // MLDv1 and starts to listen to multicast traffic. 235 // In the fallback case, ExcludeSourceSpecificGroup and 236 // IncludeSourceSpecificGroup may return an error. 237 package ipv6 // import "golang.org/x/net/ipv6" 238 239 // BUG(mikio): This package is not implemented on JS, NaCl and Plan 9.