bwallocation

README

Bandwidth Allocation System Library

bwallocation is a go library for establishing bandwidth reservations in the bandwidth allocation system.

Installation

go get -u github.com/anapaya/bwallocation/cmd/bwreserver

Usage

This package defines a go library to interact with the bandwidth allocation system. Check the go documentation for more details.

The sample application bwreserver showcases how bandwidth reservations can be obtained and used. The application runs in client and server mode.

Server Usage

Usage:
  bwreserver server [flags]

Examples:
  bwreserver server --local :9000

Flags:
      --dispatcher string   dispatcher socket (default "/run/shm/dispatcher/default.sock")
  -h, --help                help for server
      --local udp-addr      Address to listen on (default :9000)
      --log.level string    Console logging level verbosity (debug|info|error)
      --pprof tcp-addr      Address to serve pprof (default :0)
      --sciond string       SCION Daemon address (default "127.0.0.1:30255")

Client Usage

The client supports two protocols UDP/SCION and QUIC/SCION. By default UDP/SCION
is used. QUIC/SCION can be enabled with the appropriate flag.

The paths can be filtered according to a sequence. A sequence is a string of
space separated HopPredicates. A Hop Predicate (HP) is of the form
'ISD-AS#IF,IF'. The first IF means the inbound interface (the interface where
packet enters the AS) and the second IF means the outbound interface (the
interface where packet leaves the AS).  0 can be used as a wildcard for ISD, AS
and both IF elements independently.

HopPredicate Examples:

  Match any:                               0
  Match ISD 1:                             1
  Match AS 1-ff00:0:133:                   1-ff00:0:133
  Match IF 2 of AS 1-ff00:0:133:           1-ff00:0:133#2
  Match inbound IF 2 of AS 1-ff00:0:133:   1-ff00:0:133#2,0
  Match outbound IF 2 of AS 1-ff00:0:133:  1-ff00:0:133#0,2

Sequence Examples:

  sequence: "1-ff00:0:133#0 1-ff00:0:120#2,1 0 0 1-ff00:0:110#0"

The above example specifies a path from any interface in AS 1-ff00:0:133 to
two subsequent interfaces in AS 1-ff00:0:120 (entering on interface 2 and
exiting on interface 1), then there are two wildcards that each match any AS.
The path must end with any interface in AS 1-ff00:0:110.

  sequence: "1-ff00:0:133#1 1+ 2-ff00:0:1? 2-ff00:0:233#1"

The above example includes operators and specifies a path from interface
1-ff00:0:133#1 through multiple ASes in ISD 1, that may (but does not need to)
traverse AS 2-ff00:0:1 and then reaches its destination on 2-ff00:0:233#1.

Available operators:

  ? (the preceding HopPredicate may appear at most once)
  + (the preceding ISD-level HopPredicate must appear at least once)
  * (the preceding ISD-level HopPredicate may appear zero or more times)
  | (logical OR)

Usage:
  bwreserver client <server-addr> [flags]

Examples:
  bwreserver client 1-ff00:0:112,127.0.0.1:9000 -s 5mbps -d 10
  bwreserver client 1-ff00:0:112,127.0.0.1:9000 -s 10mbps -r 5mbps
  bwreserver client 1-ff00:0:112,127.0.0.1:9000 --text


Flags:
  -d, --duration int          duration of the data transmission in seconds.
                              0 or negative values will keep the data transmission going indefinitely.
  -h, --help                  help for client
  -i, --interactive           interactive mode
      --local ip              IP address to listen on
      --log.level string      Console logging level verbosity (debug|info|error)
      --payload int           payload size in bytes (default 1280)
      --pprof tcp-addr        Address to serve pprof (default :0)
      --quic                  use QUIC when sending data. If not specified, UDP is used.
  -r, --reservation string    bandwidth to reserve. Setting this lower than sending rate simulates malicious behavior.
                              supported values:
                                <bandwidth>:  Reserve the specified bandwidth
                                sending-rate: Use same value as sending-rate
                                none:         Do not reserve any bandwidth
                               (default "sending-rate")
      --sciond string         SCION Daemon address (default "127.0.0.1:30255")
  -s, --sending-rate string   rate the client attempts to send at (default "1mbps")
      --sequence string       Space separated list of hop predicates
      --text                  use simple text mode. If not specified, the CLI widgets output is used.

Screenshots

Development

The following requirements are assumed for development:

• go v1.15
• mockgen v1.4.4
• protoc v3.11.4
• protoc-gen-go v1.22.0
• protoc-gen-go-grpc v1.0.1

Running tests

make test

Regenerating Mock Files

make mocks

Regenerating Protobuf Files

make proto

Documentation

Overview

Package bwallocation implements the control plane parts of the bandwidth allocation system for star-topologies.

At the core is the Manager. It manages bandwidth reservation subscriptions that can be used to send traffic with reserved bandwidth. Client applications that want to use bandwidth reservations to send traffic initialize the Manager and subscribe for a subscription with a set of parameters. The manager takes care of establishing and renewing the reservation for all of its entire lifetime.

Subscriptions simply return the latest reservation token that the client application should use for its communication. After the client is done using the reservation, it should close the subscription to abort unnecessary renewal. This is especially important for subscriptions with unbounded expiration time.

To use the reservation for sending traffic, simply use the Conn wrapper and pass the subscription to it.

Example

package main

import (
	"context"
	"net"
	"time"

	"github.com/anapaya/bwallocation"
	"github.com/scionproto/scion/go/lib/snet"
	"github.com/scionproto/scion/go/lib/spath"
	"github.com/scionproto/scion/go/pkg/grpc"
)

func main() {
	var (
		// conn is the underlying connection that is used to send traffic.
		conn *snet.Conn
		// deamonAddr is the TCP address where the SCION daemon is exposed.
		daemonAddr net.Addr
		// bandwidth is the bandwidth that should be reserved.
		bandwidth bwallocation.Bandwidth
		// expiration is the time until the Manager shall renew the reservation.
		expiration time.Time
		// remote is the address of the remote application.
		remote *snet.UDPAddr
		// local is the address of this application.
		local *snet.UDPAddr
		// path is the raw path that is used for creating the reservation.
		path *spath.Path
	)

	// Initialize the manager with the local SCION daemon as the service. The
	// SCION daemon proxies the requests to the correct control service
	// instance.
	manager := bwallocation.Manager{
		Service: daemonAddr,
		Dialer:  grpc.SimpleDialer{},
	}

	// Create a subscription to get the reservation token.
	sub, err := manager.Subscribe(context.Background(), bwallocation.SubscriptionInfo{
		Bandwidth:   bandwidth,
		Destination: remote,
		Source:      local,
		Expiration:  expiration,
		Path:        path,
	})
	if err != nil {
		// Handle error.
	}
	// Close the subscription as soon as it is no longer needed.
	defer sub.Close()

	// Wrap the conn such that it uses the reservation token.
	rsvConn := &bwallocation.Conn{
		Conn:         conn,
		Subscription: sub,
	}
	rsvConn.Write([]byte("hello with reserved bandwidth"))
}

Index

• type Bandwidth
  • func (b Bandwidth) MarshalText() (text []byte, err error)
  • func (b Bandwidth) String() string
  • func (b *Bandwidth) UnmarshalText(text []byte) error
• type Conn
  • func (c *Conn) Write(b []byte) (int, error)
  • func (c *Conn) WriteTo(p []byte, remote net.Addr) (int, error)
• type Link
  • func (l Link) MarshalText() (text []byte, err error)
  • func (l Link) String() string
  • func (l *Link) UnmarshalText(text []byte) error
• type Manager
  • func (m *Manager) Subscribe(ctx context.Context, info SubscriptionInfo) (*Subscription, error)
• type Subscription
  • func (s *Subscription) Close()
  • func (s *Subscription) Token() (Token, error)
• type SubscriptionInfo
• type Token

Examples

• Package

Types

type Bandwidth

type Bandwidth uint64

Bandwidth is the bandwidth in bps

func (Bandwidth) MarshalText

func (b Bandwidth) MarshalText() (text []byte, err error)

func (Bandwidth) String

func (b Bandwidth) String() string

func (*Bandwidth) UnmarshalText

func (b *Bandwidth) UnmarshalText(text []byte) error

type Conn

type Conn struct {
	*snet.Conn
	Subscription *Subscription
}

Conn is a wrapper for a snet.Conn that injects the reservation token fetched from the configured subscription.

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

func (*Conn) WriteTo

func (c *Conn) WriteTo(p []byte, remote net.Addr) (int, error)

type Link

type Link struct {
	IA        addr.IA
	Interface uint64
}

Link represents a link from a leaf AS to the provider.

func (Link) MarshalText

func (l Link) MarshalText() (text []byte, err error)

func (Link) String

func (l Link) String() string

func (*Link) UnmarshalText

func (l *Link) UnmarshalText(text []byte) error

type Manager

type Manager struct {
	// Service is the address that exposes the bandwidth allocation service.
	// Usually, this should be the SCION daemon address.
	Service net.Addr
	// Dialer is the gRPC dialer that is used to connect to the service.
	Dialer grpc.Dialer
	// Logger is used for logging. If nil, nothing is logged.
	Logger log.Logger

	// FetchInterval indicates the minimum interval between successive
	// reservation renewal. If zero, the default interval is used.
	FetchInterval time.Duration
	// FetchLeadTime indicates the minimum remaining token validity before the
	// reservation is renewed. If zero, default lead time is used.
	FetchLeadTime time.Duration
	// MaxExpiry indicates the maximum reservation validity period that is
	// requested. If zero, the default max expiry is used.
	MaxExpiry time.Duration
}

Manager manages bandwidth reservation subscriptions that can be used to to send traffic with reserved bandwidth.

func (*Manager) Subscribe

func (m *Manager) Subscribe(ctx context.Context, info SubscriptionInfo) (*Subscription, error)

Subscribe subscribes for a bandwidth reservation. The subscription automatically renews the reservation token and must be closed after it is no longer required.

type Subscription

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

Subscription is a bandwidth reservation subscription that is periodically updated with a token.

func (*Subscription) Close

func (s *Subscription) Close()

Close closes the subscription. It must be called after the subscription is no longer required.

func (*Subscription) Token

func (s *Subscription) Token() (Token, error)

Token returns the currently active token. The contents must not be modified.

type SubscriptionInfo

type SubscriptionInfo struct {
	// Source is the local address of the connection bandwidth should be
	// reserved on.
	Source *snet.UDPAddr
	// Destination is the remote address of the connection bandwidth should be
	// reserved on.
	Destination *snet.UDPAddr
	// Path is the original SCION path on which a bandwidth reservation should
	// be established.
	Path *spath.Path
	// Bandwidth is the bandwidth the reservation should have. It must be a
	// multiple of 1mbps, i.e., divisible by 1e6.
	Bandwidth Bandwidth
	// Expiration is the desired expiration time. For the zero value, the
	// Manager continuously renews the reservation. In case the bandwidth
	// allocation service is not willing to handout a reservation until expiry.
	// The manager continuously renews reservations until the expiration time is
	// reached.
	Expiration time.Time
}

SubscriptionInfo is the information for a bandwidth reservation subscription.

type Token

type Token struct {
	Source      *snet.UDPAddr
	Destination *snet.UDPAddr
	Expiration  time.Time
	Path        *spath.Path
}

Token is the reservation token used to send traffic. Client code usually does not need to interact with the token directly.