Documentation

Overview

Package ipv6 implements IP-level socket options for the Internet Protocol version 6.

The package provides IP-level socket options that allow manipulation of IPv6 facilities. The IPv6 and socket options for IPv6 are defined in RFC 2460, RFC 3493, RFC 3542, RFC 3678 and RFC 4607.

Unicasting

The options for unicasting are available for net.TCPConn, net.UDPConn and net.IPConn which are created as network connections that use the IPv6 transport. When a single TCP connection carrying a data flow of multiple packets needs to indicate the flow is important, ipv6.Conn is used to set the traffic class field on the IPv6 header for each packet.

ln, err := net.Listen("tcp6", "[::]:1024")
if err != nil {
	// error handling
}
defer ln.Close()
for {
	c, err := ln.Accept()
	if err != nil {
		// error handling
	}
	go func(c net.Conn) {
		defer c.Close()

The outgoing packets will be labeled DiffServ assured forwarding class 1 low drop precedence, known as AF11 packets.

		if err := ipv6.NewConn(c).SetTrafficClass(DiffServAF11); err != nil {
			// error handling
		}
		if _, err := c.Write(data); err != nil {
			// error handling
		}
	}(c)
}

Multicasting

The options for multicasting are available for net.UDPConn and net.IPconn which are created as network connections that use the IPv6 transport. A few network facilities must be prepared before you begin multicasting, at a minimum joining network interfaces and multicast groups.

en0, err := net.InterfaceByName("en0")
if err != nil {
	// error handling
}
en1, err := net.InterfaceByIndex(911)
if err != nil {
	// error handling
}
group := net.ParseIP("ff02::114")

First, an application listens to an appropriate address with an appropriate service port.

c, err := net.ListenPacket("udp6", "[::]:1024")
if err != nil {
	// error handling
}
defer c.Close()

Second, the application joins multicast groups, starts listening to the groups on the specified network interfaces. Note that the service port for transport layer protocol does not matter with this operation as joining groups affects only network and link layer protocols, such as IPv6 and Ethernet.

p := ipv6.NewPacketConn(c)
if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil {
	// error handling
}
if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil {
	// error handling
}

The application might set per packet control message transmissions between the protocol stack within the kernel. When the application needs a destination address on an incoming packet, SetControlMessage of ipv6.PacketConn is used to enable control message transmissons.

if err := p.SetControlMessage(ipv6.FlagDst, true); err != nil {
	// error handling
}

The application could identify whether the received packets are of interest by using the control message that contains the destination address of the received packet.

b := make([]byte, 1500)
for {
	n, rcm, src, err := p.ReadFrom(b)
	if err != nil {
		// error handling
	}
	if rcm.Dst.IsMulticast() {
		if rcm.Dst.Equal(group)
			// joined group, do something
		} else {
			// unknown group, discard
			continue
		}
	}

The application can also send both unicast and multicast packets.

	p.SetTrafficClass(DiffServCS0)
	p.SetHopLimit(16)
	if _, err := p.WriteTo(data[:n], nil, src); err != nil {
		// error handling
	}
	dst := &net.UDPAddr{IP: group, Port: 1024}
	wcm := ipv6.ControlMessage{TrafficClass: DiffServCS7, HopLimit: 1}
	for _, ifi := range []*net.Interface{en0, en1} {
		wcm.IfIndex = ifi.Index
		if _, err := p.WriteTo(data[:n], &wcm, dst); err != nil {
			// error handling
		}
	}
}

More multicasting

An application that uses PacketConn may join multiple multicast groups. For example, a UDP listener with port 1024 might join two different groups across over two different network interfaces by using:

c, err := net.ListenPacket("udp6", "[::]:1024")
if err != nil {
	// error handling
}
defer c.Close()
p := ipv6.NewPacketConn(c)
if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::1:114")}); err != nil {
	// error handling
}
if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
	// error handling
}
if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
	// error handling
}

It is possible for multiple UDP listeners that listen on the same UDP port to join the same multicast group. The net package will provide a socket that listens to a wildcard address with reusable UDP port when an appropriate multicast address prefix is passed to the net.ListenPacket or net.ListenUDP.

c1, err := net.ListenPacket("udp6", "[ff02::]:1024")
if err != nil {
	// error handling
}
defer c1.Close()
c2, err := net.ListenPacket("udp6", "[ff02::]:1024")
if err != nil {
	// error handling
}
defer c2.Close()
p1 := ipv6.NewPacketConn(c1)
if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
	// error handling
}
p2 := ipv6.NewPacketConn(c2)
if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
	// error handling
}

Also it is possible for the application to leave or rejoin a multicast group on the network interface.

if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
	// error handling
}
if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
	// error handling
}

Source-specific multicasting

An application that uses PacketConn on MLDv2 supported platform is able to join source-specific multicast groups as described in RFC 3678. The application may use JoinSourceSpecificGroup and LeaveSourceSpecificGroup for the operation known as "include" mode,

ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
	// error handling
}
if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
	// error handling
}

or JoinGroup, ExcludeSourceSpecificGroup, IncludeSourceSpecificGroup and LeaveGroup for the operation known as "exclude" mode.

exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
if err := p.JoinGroup(en0, &ssmgroup); err != nil {
	// error handling
}
if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
	// error handling
}
if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
	// error handling
}

Note that it depends on each platform implementation what happens when an application which runs on MLDv2 unsupported platform uses JoinSourceSpecificGroup and LeaveSourceSpecificGroup. In general the platform tries to fall back to conversations using MLDv1 and starts to listen to multicast traffic. In the fallback case, ExcludeSourceSpecificGroup and IncludeSourceSpecificGroup may return an error.

Index

Examples

Constants

View Source
const (
	Version   = 6  // protocol version
	HeaderLen = 40 // header length
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

    A Conn represents a network endpoint that uses IPv6 transport. It allows to set basic IP-level socket options such as traffic class and hop limit.

    Example (MarkingTCP)
    Output:
    
    

    func NewConn

    func NewConn(c net.Conn) *Conn

      NewConn returns a new Conn.

      func (*Conn) HopLimit

      func (c *Conn) HopLimit() (int, error)

        HopLimit returns the hop limit field value for outgoing packets.

        func (*Conn) PathMTU

        func (c *Conn) PathMTU() (int, error)

          PathMTU returns a path MTU value for the destination associated with the endpoint.

          func (*Conn) SetHopLimit

          func (c *Conn) SetHopLimit(hoplim int) error

            SetHopLimit sets the hop limit field value for future outgoing packets.

            func (*Conn) SetTrafficClass

            func (c *Conn) SetTrafficClass(tclass int) error

              SetTrafficClass sets the traffic class field value for future outgoing packets.

              func (*Conn) TrafficClass

              func (c *Conn) TrafficClass() (int, error)

                TrafficClass returns the traffic class field value for outgoing packets.

                type ControlFlags

                type ControlFlags uint

                  A ControlFlags represents per packet basis IP-level socket option control flags.

                  const (
                  	FlagTrafficClass ControlFlags = 1 << iota // pass the traffic class on the received packet
                  	FlagHopLimit                              // pass the hop limit on the received packet
                  	FlagSrc                                   // pass the source address on the received packet
                  	FlagDst                                   // pass the destination address on the received packet
                  	FlagInterface                             // pass the interface index on the received packet
                  	FlagPathMTU                               // pass the path MTU on the received packet path
                  )

                  type ControlMessage

                  type ControlMessage struct {
                  	// Receiving socket options: SetControlMessage allows to
                  	// receive the options from the protocol stack using ReadFrom
                  	// method of PacketConn.
                  	//
                  	// Specifying socket options: ControlMessage for WriteTo
                  	// method of PacketConn allows to send the options to the
                  	// protocol stack.
                  	//
                  	TrafficClass int    // traffic class, must be 1 <= value <= 255 when specifying
                  	HopLimit     int    // hop limit, must be 1 <= value <= 255 when specifying
                  	Src          net.IP // source address, specifying only
                  	Dst          net.IP // destination address, receiving only
                  	IfIndex      int    // interface index, must be 1 <= value when specifying
                  	NextHop      net.IP // next hop address, specifying only
                  	MTU          int    // path MTU, receiving only
                  }

                    A ControlMessage represents per packet basis IP-level socket options.

                    func (*ControlMessage) String

                    func (cm *ControlMessage) String() string
                    type Header struct {
                    	Version      int    // protocol version
                    	TrafficClass int    // traffic class
                    	FlowLabel    int    // flow label
                    	PayloadLen   int    // payload length
                    	NextHeader   int    // next header
                    	HopLimit     int    // hop limit
                    	Src          net.IP // source address
                    	Dst          net.IP // destination address
                    }

                      A Header represents an IPv6 base header.

                      func ParseHeader

                      func ParseHeader(b []byte) (*Header, error)

                        ParseHeader parses b as an IPv6 base header.

                        func (*Header) String

                        func (h *Header) String() string

                        type ICMPFilter

                        type ICMPFilter struct {
                        	// contains filtered or unexported fields
                        }

                          An ICMPFilter represents an ICMP message filter for incoming packets. The filter belongs to a packet delivery path on a host and it cannot interact with forwarding packets or tunnel-outer packets.

                          Note: RFC 2460 defines a reasonable role model. A node means a device that implements IP. A router means a node that forwards IP packets not explicitly addressed to itself, and a host means a node that is not a router.

                          func (*ICMPFilter) Accept

                          func (f *ICMPFilter) Accept(typ ICMPType)

                            Accept accepts incoming ICMP packets including the type field value typ.

                            func (*ICMPFilter) Block

                            func (f *ICMPFilter) Block(typ ICMPType)

                              Block blocks incoming ICMP packets including the type field value typ.

                              func (*ICMPFilter) SetAll

                              func (f *ICMPFilter) SetAll(block bool)

                                SetAll sets the filter action to the filter.

                                func (*ICMPFilter) WillBlock

                                func (f *ICMPFilter) WillBlock(typ ICMPType) bool

                                  WillBlock reports whether the ICMP type will be blocked.

                                  type ICMPType

                                  type ICMPType int

                                    An ICMPType represents a type of ICMP message.

                                    const (
                                    	ICMPTypeDestinationUnreachable                ICMPType = 1   // Destination Unreachable
                                    	ICMPTypePacketTooBig                          ICMPType = 2   // Packet Too Big
                                    	ICMPTypeTimeExceeded                          ICMPType = 3   // Time Exceeded
                                    	ICMPTypeParameterProblem                      ICMPType = 4   // Parameter Problem
                                    	ICMPTypeEchoRequest                           ICMPType = 128 // Echo Request
                                    	ICMPTypeEchoReply                             ICMPType = 129 // Echo Reply
                                    	ICMPTypeMulticastListenerQuery                ICMPType = 130 // Multicast Listener Query
                                    	ICMPTypeMulticastListenerReport               ICMPType = 131 // Multicast Listener Report
                                    	ICMPTypeMulticastListenerDone                 ICMPType = 132 // Multicast Listener Done
                                    	ICMPTypeRouterSolicitation                    ICMPType = 133 // Router Solicitation
                                    	ICMPTypeRouterAdvertisement                   ICMPType = 134 // Router Advertisement
                                    	ICMPTypeNeighborSolicitation                  ICMPType = 135 // Neighbor Solicitation
                                    	ICMPTypeNeighborAdvertisement                 ICMPType = 136 // Neighbor Advertisement
                                    	ICMPTypeRedirect                              ICMPType = 137 // Redirect Message
                                    	ICMPTypeRouterRenumbering                     ICMPType = 138 // Router Renumbering
                                    	ICMPTypeNodeInformationQuery                  ICMPType = 139 // ICMP Node Information Query
                                    	ICMPTypeNodeInformationResponse               ICMPType = 140 // ICMP Node Information Response
                                    	ICMPTypeInverseNeighborDiscoverySolicitation  ICMPType = 141 // Inverse Neighbor Discovery Solicitation Message
                                    	ICMPTypeInverseNeighborDiscoveryAdvertisement ICMPType = 142 // Inverse Neighbor Discovery Advertisement Message
                                    	ICMPTypeVersion2MulticastListenerReport       ICMPType = 143 // Version 2 Multicast Listener Report
                                    	ICMPTypeHomeAgentAddressDiscoveryRequest      ICMPType = 144 // Home Agent Address Discovery Request Message
                                    	ICMPTypeHomeAgentAddressDiscoveryReply        ICMPType = 145 // Home Agent Address Discovery Reply Message
                                    	ICMPTypeMobilePrefixSolicitation              ICMPType = 146 // Mobile Prefix Solicitation
                                    	ICMPTypeMobilePrefixAdvertisement             ICMPType = 147 // Mobile Prefix Advertisement
                                    	ICMPTypeCertificationPathSolicitation         ICMPType = 148 // Certification Path Solicitation Message
                                    	ICMPTypeCertificationPathAdvertisement        ICMPType = 149 // Certification Path Advertisement Message
                                    	ICMPTypeMulticastRouterAdvertisement          ICMPType = 151 // Multicast Router Advertisement
                                    	ICMPTypeMulticastRouterSolicitation           ICMPType = 152 // Multicast Router Solicitation
                                    	ICMPTypeMulticastRouterTermination            ICMPType = 153 // Multicast Router Termination
                                    	ICMPTypeFMIPv6                                ICMPType = 154 // FMIPv6 Messages
                                    	ICMPTypeRPLControl                            ICMPType = 155 // RPL Control Message
                                    	ICMPTypeILNPv6LocatorUpdate                   ICMPType = 156 // ILNPv6 Locator Update Message
                                    	ICMPTypeDuplicateAddressRequest               ICMPType = 157 // Duplicate Address Request
                                    	ICMPTypeDuplicateAddressConfirmation          ICMPType = 158 // Duplicate Address Confirmation
                                    )

                                      Internet Control Message Protocol version 6 (ICMPv6) Parameters, Updated: 2014-09-22

                                      func (ICMPType) Protocol

                                      func (typ ICMPType) Protocol() int

                                        Protocol returns the ICMPv6 protocol number.

                                        func (ICMPType) String

                                        func (typ ICMPType) String() string

                                        type PacketConn

                                        type PacketConn struct {
                                        	// contains filtered or unexported fields
                                        }

                                          A PacketConn represents a packet network endpoint that uses IPv6 transport. It is used to control several IP-level socket options including IPv6 header manipulation. It also provides datagram based network I/O methods specific to the IPv6 and higher layer protocols such as OSPF, GRE, and UDP.

                                          Example (AdvertisingOSPFHello)
                                          Output:
                                          
                                          
                                          Example (ServingOneShotMulticastDNS)
                                          Output:
                                          
                                          
                                          Example (TracingIPPacketRoute)
                                          Output:
                                          
                                          

                                          func NewPacketConn

                                          func NewPacketConn(c net.PacketConn) *PacketConn

                                            NewPacketConn returns a new PacketConn using c as its underlying transport.

                                            func (*PacketConn) Checksum

                                            func (c *PacketConn) Checksum() (on bool, offset int, err error)

                                              Checksum reports whether the kernel will compute, store or verify a checksum for both incoming and outgoing packets. If on is true, it returns an offset in bytes into the data of where the checksum field is located.

                                              func (*PacketConn) Close

                                              func (c *PacketConn) Close() error

                                                Close closes the endpoint.

                                                func (*PacketConn) ExcludeSourceSpecificGroup

                                                func (c *PacketConn) ExcludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error

                                                  ExcludeSourceSpecificGroup excludes the source-specific group from the already joined any-source groups by JoinGroup on the interface ifi.

                                                  func (*PacketConn) HopLimit

                                                  func (c *PacketConn) HopLimit() (int, error)

                                                    HopLimit returns the hop limit field value for outgoing packets.

                                                    func (*PacketConn) ICMPFilter

                                                    func (c *PacketConn) ICMPFilter() (*ICMPFilter, error)

                                                      ICMPFilter returns an ICMP filter.

                                                      func (*PacketConn) IncludeSourceSpecificGroup

                                                      func (c *PacketConn) IncludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error

                                                        IncludeSourceSpecificGroup includes the excluded source-specific group by ExcludeSourceSpecificGroup again on the interface ifi.

                                                        func (*PacketConn) JoinGroup

                                                        func (c *PacketConn) JoinGroup(ifi *net.Interface, group net.Addr) error

                                                          JoinGroup joins the group address group on the interface ifi. By default all sources that can cast data to group are accepted. It's possible to mute and unmute data transmission from a specific source by using ExcludeSourceSpecificGroup and IncludeSourceSpecificGroup. JoinGroup uses the system assigned multicast interface when ifi is nil, although this is not recommended because the assignment depends on platforms and sometimes it might require routing configuration.

                                                          func (*PacketConn) JoinSourceSpecificGroup

                                                          func (c *PacketConn) JoinSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error

                                                            JoinSourceSpecificGroup joins the source-specific group comprising group and source on the interface ifi. JoinSourceSpecificGroup uses the system assigned multicast interface when ifi is nil, although this is not recommended because the assignment depends on platforms and sometimes it might require routing configuration.

                                                            func (*PacketConn) LeaveGroup

                                                            func (c *PacketConn) LeaveGroup(ifi *net.Interface, group net.Addr) error

                                                              LeaveGroup leaves the group address group on the interface ifi regardless of whether the group is any-source group or source-specific group.

                                                              func (*PacketConn) LeaveSourceSpecificGroup

                                                              func (c *PacketConn) LeaveSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error

                                                                LeaveSourceSpecificGroup leaves the source-specific group on the interface ifi.

                                                                func (*PacketConn) MulticastHopLimit

                                                                func (c *PacketConn) MulticastHopLimit() (int, error)

                                                                  MulticastHopLimit returns the hop limit field value for outgoing multicast packets.

                                                                  func (*PacketConn) MulticastInterface

                                                                  func (c *PacketConn) MulticastInterface() (*net.Interface, error)

                                                                    MulticastInterface returns the default interface for multicast packet transmissions.

                                                                    func (*PacketConn) MulticastLoopback

                                                                    func (c *PacketConn) MulticastLoopback() (bool, error)

                                                                      MulticastLoopback reports whether transmitted multicast packets should be copied and send back to the originator.

                                                                      func (*PacketConn) ReadFrom

                                                                      func (c *PacketConn) ReadFrom(b []byte) (n int, cm *ControlMessage, src net.Addr, err error)

                                                                        ReadFrom reads a payload of the received IPv6 datagram, from the endpoint c, copying the payload into b. It returns the number of bytes copied into b, the control message cm and the source address src of the received datagram.

                                                                        func (*PacketConn) SetChecksum

                                                                        func (c *PacketConn) SetChecksum(on bool, offset int) error

                                                                          SetChecksum enables the kernel checksum processing. If on is ture, the offset should be an offset in bytes into the data of where the checksum field is located.

                                                                          func (*PacketConn) SetControlMessage

                                                                          func (c *PacketConn) SetControlMessage(cf ControlFlags, on bool) error

                                                                            SetControlMessage allows to receive the per packet basis IP-level socket options.

                                                                            func (*PacketConn) SetDeadline

                                                                            func (c *PacketConn) SetDeadline(t time.Time) error

                                                                              SetDeadline sets the read and write deadlines associated with the endpoint.

                                                                              func (*PacketConn) SetHopLimit

                                                                              func (c *PacketConn) SetHopLimit(hoplim int) error

                                                                                SetHopLimit sets the hop limit field value for future outgoing packets.

                                                                                func (*PacketConn) SetICMPFilter

                                                                                func (c *PacketConn) SetICMPFilter(f *ICMPFilter) error

                                                                                  SetICMPFilter deploys the ICMP filter.

                                                                                  func (*PacketConn) SetMulticastHopLimit

                                                                                  func (c *PacketConn) SetMulticastHopLimit(hoplim int) error

                                                                                    SetMulticastHopLimit sets the hop limit field value for future outgoing multicast packets.

                                                                                    func (*PacketConn) SetMulticastInterface

                                                                                    func (c *PacketConn) SetMulticastInterface(ifi *net.Interface) error

                                                                                      SetMulticastInterface sets the default interface for future multicast packet transmissions.

                                                                                      func (*PacketConn) SetMulticastLoopback

                                                                                      func (c *PacketConn) SetMulticastLoopback(on bool) error

                                                                                        SetMulticastLoopback sets whether transmitted multicast packets should be copied and send back to the originator.

                                                                                        func (*PacketConn) SetReadDeadline

                                                                                        func (c *PacketConn) SetReadDeadline(t time.Time) error

                                                                                          SetReadDeadline sets the read deadline associated with the endpoint.

                                                                                          func (*PacketConn) SetTrafficClass

                                                                                          func (c *PacketConn) SetTrafficClass(tclass int) error

                                                                                            SetTrafficClass sets the traffic class field value for future outgoing packets.

                                                                                            func (*PacketConn) SetWriteDeadline

                                                                                            func (c *PacketConn) SetWriteDeadline(t time.Time) error

                                                                                              SetWriteDeadline sets the write deadline associated with the endpoint.

                                                                                              func (*PacketConn) TrafficClass

                                                                                              func (c *PacketConn) TrafficClass() (int, error)

                                                                                                TrafficClass returns the traffic class field value for outgoing packets.

                                                                                                func (*PacketConn) WriteTo

                                                                                                func (c *PacketConn) WriteTo(b []byte, cm *ControlMessage, dst net.Addr) (n int, err error)

                                                                                                  WriteTo writes a payload of the IPv6 datagram, to the destination address dst through the endpoint c, copying the payload from b. It returns the number of bytes written. The control message cm allows the IPv6 header fields and the datagram path to be specified. The cm may be nil if control of the outgoing datagram is not required.