network

Documentation

Overview

Package network contains scripts and abstractions for setting up TAP-device based networks for a set of QEMU virtual machines.

Each virtual machine will get a TAP device, represented as a network, the TAP device will automatically get an IP address and DNS server using DHCP. The DNS server will resolve the "taskcluster" domains to the meta-data IP address. Request to the meta-data IP will be forwarded to the handler registered for the network instance.

This package uses iptables to lock down network and ensure that the virtual machine attached to a TAP device can't contact the meta-data handler of another virtual machine.

Index

• Variables
• type Network
  • func (n *Network) NetDev(ID string) string
  • func (n *Network) Release()
  • func (n *Network) SetHandler(handler http.Handler)
• type Pool
  • func NewPool(options PoolOptions) (*Pool, error)
  • func (p *Pool) Dispose() error
  • func (p *Pool) Network() (*Network, error)
  • func (p *Pool) Size() int
• type PoolOptions
• type UserNetwork
  • func NewUserNetwork(socketFolder string) (*UserNetwork, error)
  • func (n *UserNetwork) NetDev(ID string) string
  • func (n *UserNetwork) Release()
  • func (n *UserNetwork) SetHandler(handler http.Handler)

Variables

var ErrAllNetworksInUse = errors.New("All networks in the network.Pool are in use")

ErrAllNetworksInUse is used to signal that we don't have any more networks available and, thus, can't return one.

var PoolConfigSchema schematypes.Schema = schematypes.Object{
	Properties: schematypes.Properties{
		"subnets": schematypes.Integer{
			Description: util.Markdown(`
				Number of subnets to creates.
				This determines the maximum number of concurrent VMs the worker can run.

				Each subnet defines a set chains and rules in 'iptables', and thus,
				incurs some kernel overhead. It is recommended to create more subnets
				than needed, but to avoid creating the maximum unless required.
			`),
			Minimum: 1,
			Maximum: 100,
		},
		"vpnConnections": schematypes.Array{
			Title: "VPN Connections",
			Description: util.Markdown(`
				VPN Connections to be setup by the worker and exposed to the virtual
				machines, such that connections can be opened from the virtual machine
				to the routes exposed.

				Note: servers on the VPN will not be able to open incoming connections
				to the virtual machines, as the VMs will sit behind NAT.
			`),
			Items: openvpn.ConfigSchema,
		},
		"srvRecords": schematypes.Array{
			Title: "SRV Records",
			Items: schematypes.Object{
				Title: "SRV Record",
				Description: util.Markdown(`
					SRV record to be inserted in the DNS server advertized to the
					virtual machine. This can be useful for auto-discovery of resources
					located in VPN connections exposed to the VM.

					For details on properties please refer to
					[RFC 2782](https://tools.ietf.org/html/rfc2782).
				`),
				Properties: schematypes.Properties{
					"service":  schematypes.String{},
					"protocol": schematypes.String{},
					"domain":   schematypes.String{},
					"target":   schematypes.String{},
					"port":     schematypes.Integer{Minimum: 0, Maximum: 65535},
					"priority": schematypes.Integer{Minimum: 0, Maximum: 65535},
					"weight":   schematypes.Integer{Minimum: 0, Maximum: 65535},
				},
				Required: []string{
					"service", "protocol", "target", "port",
				},
			},
		},
		"hostRecords": schematypes.Array{
			Title: "Host Records",
			Items: schematypes.Object{
				Title: "Host Record",
				Description: util.Markdown(`
					A and AAAA records to insert in the DNS server advertized to the
					virtual machine.
				`),
				Properties: schematypes.Properties{
					"names": schematypes.Array{Items: schematypes.String{}},
					"ipv4":  schematypes.String{},
					"ipv6":  schematypes.String{},
				},
				Required: []string{"names"},
			},
		},
	},
	Required: []string{"subnets"},
}

PoolConfigSchema is the configuration schema to be satisfied by configuration passed to NewPool()

Types

type Network

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

Network is provides the interface for using a TAP device, and releasing it.

func (*Network) NetDev

func (n *Network) NetDev(ID string) string

NetDev returns the argument for the QEMU -netdev option.

func (*Network) Release

func (n *Network) Release()

Release returns this network to the Pool

func (*Network) SetHandler

func (n *Network) SetHandler(handler http.Handler)

SetHandler sets the http.handler for meta-data service for this tap-device.

type Pool

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

Pool manages a static set of networks (TAP devices).

func NewPool

func NewPool(options PoolOptions) (*Pool, error)

NewPool creates N virtual networks and returns Pool. This should be called before the worker starts operating, we don't wish to dynamically reconfigure networks at runtime.

func (*Pool) Dispose

func (p *Pool) Dispose() error

Dispose deletes all the networks created, should not be called while any of networks are in use.

func (*Pool) Network

func (p *Pool) Network() (*Network, error)

Network returns an unused network, or nil if no network is available.

func (*Pool) Size

func (p *Pool) Size() int

Size returns the number of networks in the network Pool

type PoolOptions

type PoolOptions struct {
	Config           interface{} // Must satisfy PoolConfigSchema
	Monitor          runtime.Monitor
	TemporaryStorage runtime.TemporaryStorage
}

PoolOptions specifies options required by NewPool

type UserNetwork

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

UserNetwork provides an unsafe network implementation for use when building and testing images locally (without root access).

func NewUserNetwork

func NewUserNetwork(socketFolder string) (*UserNetwork, error)

NewUserNetwork returns a Network implementation using the QEMU user-space network stack. This doesn't provide the same level of isolation, but the meta-data service should be sufficiently isolated.

func (*UserNetwork) NetDev

func (n *UserNetwork) NetDev(ID string) string

NetDev returns the argument for the QEMU option -netdev

func (*UserNetwork) Release

func (n *UserNetwork) Release()

Release frees all resources used by this network.

func (*UserNetwork) SetHandler

func (n *UserNetwork) SetHandler(handler http.Handler)

SetHandler takes an http.Handler to be used for meta-data requests.