README
¶
vnet
A virtual network layer for pion.
Overview
Goals
- To make NAT traversal tests easy.
- To emulate packet impairment at application level for testing.
- To monitor packets at specified arbitrary interfaces.
Features
- Configurable virtual LAN and WAN
- Virtually hosted ICE servers
Virtual network components
Top View
......................................
: Virtual Network (vnet) :
: :
+-------+ * 1 +----+ +--------+ :
| :App |------------>|:Net|--o<-----|:Router | :
+-------+ +----+ | | :
+-----------+ * 1 +----+ | | :
|:STUNServer|-------->|:Net|--o<-----| | :
+-----------+ +----+ | | :
+-----------+ * 1 +----+ | | :
|:TURNServer|-------->|:Net|--o<-----| | :
+-----------+ +----+ [1] | | :
: 1 | | 1 <<has>> :
: +---<>| |<>----+ [2] :
: | +--------+ | :
To form | *| v 0..1 :
a subnet tree | o [3] +-----+ :
: | ^ |:NAT | :
: | | +-----+ :
: +-------+ :
......................................
Note:
o: NIC (Netork Interface Controller)
[1]: Net implments NIC interface.
[2]: Root router has no NAT. All child routers have a NAT always.
[3]: Router implements NIC interface for accesses from the
parent router.
Net
Net provides 3 interfaces:
- Configuration API (direct)
- Network API via Net (equivalent to net.Xxx())
- Router access via NIC interface
(Pion module/app, ICE servers, etc.)
+-----------+
| :App |
+-----------+
* |
| <<uses>>
1 v
+---------+ 1 * +-----------+ 1 * +-----------+ 1 * +------+
..| :Router |----+------>o--| :Net |<>------|:Interface |<>------|:Addr |
+---------+ | NIC +-----------+ +-----------+ +------+
| <<interface>> (vnet.Interface) (net.Addr)
|
| * +-----------+ 1 * +-----------+ 1 * +------+
+------>o--| :Router |<>------|:Interface |<>------|:Addr |
NIC +-----------+ +-----------+ +------+
<<interface>> (vnet.Interface) (net.Addr)
The instance of
Netwill be the one passed around the project. Net class has public methods for configuration and for application use.
Implementation
Design Policy
- Each pion package should have config object which has
Net(of type vnet.Net) property. (just like how we distributeLoggerFactorythroughout the pion project. - DNS => a simple dictionary (global)?
- Each Net has routing capability (a goroutine)
- Use interface provided net package as much as possible
- Routers are connected in a tree structure (no loop is allowed)
- To simplify routing
- Easy to control / monitor (stats, etc)
- Root router has no NAT (== Internet / WAN)
- Non-root router has a NAT always
- When a Net is instantiated, it will automatically add
lo0andeth0interface, andlo0will have one IP address, 127.0.0.1. (this is not used in pion/ice, however) - When a Net is added to a router, the router automatically assign an IP address for
eth0interface.- For simplicity
- User data won't fragment, but optionally drop chunk larger than MTU
- IPv6 is not supported
Basic steps for setting up virtual network
- Create a root router (WAN)
- Create child routers and add to its parent (forms a tree, don't create a loop!)
- Add instances of Net to each routers
- Call Stop(), or Stop(), on the top router, which propages all other routers
Example: WAN with one endpoint (vnet)
import (
"net"
"github.com/mudutv/transport/vnet"
"github.com/mudutv/logging"
)
// Create WAN (a root router).
wan, err := vnet.NewRouter(&RouterConfig{
CIDR: "0.0.0.0/0",
LoggerFactory: logging.NewDefaultLoggerFactory(),
})
// Create a network.
// You can specify a static IP for the instance of Net to use. If not specified,
// router will assign an IP address that is contained in the router's CIDR.
nw := vnet.NewNet(&vnet.NetConfig{
StaticIP: "27.1.2.3",
})
// Add the network to the router.
// The router will assign an IP address to `nw`.
if err = wan.AddNet(nw); err != nil {
// handle error
}
// Start router.
// This will start internal goroutine to route packets.
// If you set child routers (using AddRouter), the call on the root router
// will start the rest of routers for you.
if err = wan.Start(); err != nil {
// handle error
}
//
// Your application runs here using `nw`.
//
// Stop the router.
// This will stop all internal goroutines in the router tree.
// (No need to call Stop() on child routers)
if err = wan.Stop(); err != nil {
// handle error
}
Example of how to pass around the instance of vnet.Net
The instance of vnet.Net wraps a subset of net package to enable operations
on the virtual network. Your project must be able to pass the instance to
all your routines that do network operation with net package. A typical way
is to use a config param to create your instances with the virtual network
instance (nw in the above example) like this:
type AgentConfig struct {
:
Net: *vnet.Net,
}
type Agent struct {
:
net: *vnet.Net,
}
func NetAgent(config *AgentConfig) *Agent {
if config.Net == nil {
config.Net = vnet.NewNet(nil) // defaults to native operation
}
return &Agent {
:
net: config.Net,
}
}
// a.net is the instance of vnet.Net class
func (a *Agent) listenUDP(...) error {
conn, err := a.net.ListenPacket("udp", ...)
if err != nil {
return nil, err
}
:
}
Compatibility and Support Status
net(built-in) |
vnet |
Note |
|---|---|---|
| net.Interfaces() | a.net.Interfaces() | |
| net.InterfaceByName() | a.net.InterfaceByName() | |
| net.ResolveUDPAddr() | a.net.ResolveUDPAddr() | |
| net.ListenPacket() | a.net.ListenPacket() | |
| net.ListenUDP() | a.net.ListenUDP() | (ListenPacket() is recommended) |
| net.Listen() | a.net.Listen() | (TODO) |
| net.ListenTCP() | (not supported) | (Listen() would be recommended) |
| net.Dial() | a.net.Dial() | |
| net.DialUDP() | a.net.DialUDP() | |
| net.DialTCP() | (not supported) | |
| net.Interface | vnet.Interface | |
| net.PacketConn | (use it as-is) | |
| net.UDPConn | vnet.UDPConn | Use vnet.UDPPacketConn in your code |
| net.TCPConn | vnet.TCPConn | (TODO) |
| net.Dialer | vnet.Dialer | Use a.net.CreateDialer() to create it. The use of vnet.Dialer is currently experimental. |
a.netis an instance of Net class, and types are defined under the package namevnet
Most of other
interfacetypes in net package can be used as is.
Please post a github issue when other types/methods need to be added to vnet/vnet.Net.
TODO / Next Step
- Implement TCP (TCPConn, Listen)
- Support of IPv6
- Write a bunch of examples for building virtual networks.
- Add network impairment features (on Router)
- Introduce lantecy / jitter
- Packet filtering handler (allow selectively drop packets, etc.)
- Add statistics data retrieval
- Total number of packets forward by each router
- Total number of packet loss
- Total number of connection failure (TCP)
References
Code experiments
Documentation
¶
Overview ¶
Package vnet provides a virtual network layer for pion
Index ¶
- type Chunk
- type ChunkFilter
- type Dialer
- type EndpointDependencyType
- type Interface
- type InterfaceBase
- type NATMode
- type NATType
- type NIC
- type Net
- func (n *Net) CreateDialer(dialer *net.Dialer) Dialer
- func (n *Net) Dial(network, address string) (net.Conn, error)
- func (n *Net) DialUDP(network string, laddr, raddr *net.UDPAddr) (UDPPacketConn, error)
- func (n *Net) InterfaceByName(name string) (*Interface, error)
- func (n *Net) Interfaces() ([]*Interface, error)
- func (n *Net) IsVirtual() bool
- func (n *Net) ListenPacket(network string, address string) (net.PacketConn, error)
- func (n *Net) ListenUDP(network string, locAddr *net.UDPAddr) (UDPPacketConn, error)
- func (n *Net) ResolveUDPAddr(network, address string) (*net.UDPAddr, error)
- type NetConfig
- type Router
- type RouterConfig
- type UDPConn
- func (c *UDPConn) Close() error
- func (c *UDPConn) LocalAddr() net.Addr
- func (c *UDPConn) Read(b []byte) (int, error)
- func (c *UDPConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)
- func (c *UDPConn) RemoteAddr() net.Addr
- func (c *UDPConn) SetDeadline(t time.Time) error
- func (c *UDPConn) SetReadDeadline(t time.Time) error
- func (c *UDPConn) SetWriteDeadline(t time.Time) error
- func (c *UDPConn) Write(b []byte) (int, error)
- func (c *UDPConn) WriteTo(p []byte, addr net.Addr) (n int, err error)
- type UDPPacketConn
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Chunk ¶
type Chunk interface {
SourceAddr() net.Addr
DestinationAddr() net.Addr
UserData() []byte
Tag() string
Clone() Chunk
Network() string // returns "udp" or "tcp"
String() string
// contains filtered or unexported methods
}
Chunk represents a packet passed around in the vnet
type ChunkFilter ¶
ChunkFilter is a handler users can add to filter chunks. If the filter returns false, the packet will be dropped.
type Dialer ¶
Dialer is identical to net.Dialer excepts that its methods (Dial, DialContext) are overridden to use virtual network. Use vnet.CreateDialer() to create an instance of this Dialer.
type EndpointDependencyType ¶
type EndpointDependencyType uint8
EndpointDependencyType defines a type of behavioral dependendency on the remote endpoint's IP address or port number. This is used for the two kinds of behaviors:
- Port mapping behavior
- Filtering behavior
See: https://tools.ietf.org/html/rfc4787
const ( // EndpointIndependent means the behavior is independent of the endpoint's address or port EndpointIndependent EndpointDependencyType = iota // EndpointAddrDependent means the behavior is dependent on the endpoint's address EndpointAddrDependent // EndpointAddrPortDependent means the behavior is dependent on the endpoint's address and port EndpointAddrPortDependent )
type Interface ¶
type Interface struct {
InterfaceBase
// contains filtered or unexported fields
}
Interface ...
type NATMode ¶
type NATMode uint8
NATMode defines basic behavior of the NAT
const ( // NATModeNormal means the NAT behaves as a standard NAPT (RFC 2663). NATModeNormal NATMode = iota // NATModeNAT1To1 exhibits 1:1 DNAT where the external IP address is statically mapped to // a specific local IP address with port number is preserved always between them. // When this mode is selected, MappingBehavior, FilteringBehavior, PortPreservation and // MappingLifeTime of NATType are ignored. NATModeNAT1To1 )
type NATType ¶
type NATType struct {
Mode NATMode
MappingBehavior EndpointDependencyType
FilteringBehavior EndpointDependencyType
Hairpining bool // Not implemented yet
PortPreservation bool // Not implemented yet
MappingLifeTime time.Duration
}
NATType has a set of parameters that define the behavior of NAT.
type NIC ¶
type NIC interface {
// contains filtered or unexported methods
}
NIC is a nework inerface controller that interfaces Router
type Net ¶
type Net struct {
// contains filtered or unexported fields
}
Net represents a local network stack euivalent to a set of layers from NIC up to the transport (UDP / TCP) layer.
func NewNet ¶
NewNet creates an instance of Net. If config is nil, the virtual network is disabled. (uses corresponding net.Xxxx() operations. By design, it always have lo0 and eth0 interfaces. The lo0 has the address 127.0.0.1 assigned by default. IP address for eth0 will be assigned when this Net is added to a router.
func (*Net) CreateDialer ¶
CreateDialer creates an instance of vnet.Dialer
func (*Net) InterfaceByName ¶
InterfaceByName returns the interface specified by name.
func (*Net) Interfaces ¶
Interfaces returns a list of the system's network interfaces.
func (*Net) ListenPacket ¶
ListenPacket announces on the local network address.
type NetConfig ¶
type NetConfig struct {
// StaticIPs is an array of static IP addresses to be assigned for this Net.
// If no static IP address is given, the router will automatically assign
// an IP address.
StaticIPs []string
// StaticIP is deprecated. Use StaticIPs.
StaticIP string
}
NetConfig is a bag of configuration parameters passed to NewNet().
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router ...
func (*Router) AddChunkFilter ¶
func (r *Router) AddChunkFilter(filter ChunkFilter)
AddChunkFilter adds a filter for chunks traversing this router. You may add more than one filter. The filters are called in the order of this method call. If a chunk is dropped by a filter, subsequent filter will not receive the chunk.
func (*Router) AddHost ¶
AddHost adds a mapping of hostname and an IP address to the local resolver.
type RouterConfig ¶
type RouterConfig struct {
// Name of router. If not specified, a unique name will be assigned.
Name string
// CIDR notation, like "192.0.2.0/24"
CIDR string
// StaticIPs is an array of static IP addresses to be assigned for this router.
// If no static IP address is given, the router will automatically assign
// an IP address.
// This will be ignored if this router is the root.
StaticIPs []string
// StaticIP is deprecated. Use StaticIPs.
StaticIP string
// Internal queue size
QueueSize int
// Effective only when this router has a parent router
NATType *NATType
// Minimum Delay
MinDelay time.Duration
// Max Jitter
MaxJitter time.Duration
// Logger factory
LoggerFactory logging.LoggerFactory
}
RouterConfig ...
type UDPConn ¶
type UDPConn struct {
// contains filtered or unexported fields
}
UDPConn is the implementation of the Conn and PacketConn interfaces for UDP network connections. comatible with net.PacketConn and net.Conn
func (*UDPConn) Close ¶
Close closes the connection. Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
func (*UDPConn) Read ¶
Read reads data from the connection. Read can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.
func (*UDPConn) ReadFrom ¶
ReadFrom reads a packet from the connection, copying the payload into p. It returns the number of bytes copied into p and the return address that was on the packet. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. Callers should always process the n > 0 bytes returned before considering the error err. ReadFrom can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.
func (*UDPConn) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*UDPConn) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations fail with a timeout (see type Error) instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to ReadFrom or WriteTo. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.
An idle timeout can be implemented by repeatedly extending the deadline after successful ReadFrom or WriteTo calls.
A zero value for t means I/O operations will not time out.
func (*UDPConn) SetReadDeadline ¶
SetReadDeadline sets the deadline for future ReadFrom calls and any currently-blocked ReadFrom call. A zero value for t means ReadFrom will not time out.
func (*UDPConn) SetWriteDeadline ¶
SetWriteDeadline sets the deadline for future WriteTo calls and any currently-blocked WriteTo call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means WriteTo will not time out.
func (*UDPConn) Write ¶
Write writes data to the connection. Write can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetWriteDeadline.
Source Files