topology

Documentation

Overview

Package topology wraps two versions of the topology. The first is RWTopology, which permits other packages to change topology information. The second topology type is Topology. It is used by packages that only need read access to the topology.

The full JSON format for a SCION address looks like the following:

"Addrs":{
  "IPv4": {
    "Public": {
      "Addr": "192.168.1.1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    },
    "Bind": {
      "Addr": "127.0.0.1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    }
  },
  "IPv6": {
    "Public": {
      "Addr": "2001:db8:f00:b43::1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    },
    "Bind": {
      "Addr": "2001:db8:f00:b43::1",
      "L4Port": 31000,
      "OverlayPort": 30041,
    }
  }
}

Go applications parse the above in the following manner:

• Properties not listed in the above are ignored;
• If a "Bind" property is found, parsing will return an error; bind addresses for SCION sockets are currently not supported.
• If an "OverlayPort" property is found, parsing will return an error; custom underlay ports for SCION sockets are currently not supported. NOTE: the JSON file uses the old "Overlay" term for the AS-level UDP fabric that forwards traffic. The new term for this (which is also used in the Go code base) is "Underlay".
• If both property "IPv4" and "IPv6" are present, the address is assumed to be IPv6 and only that address is used (in other words, the IPv4 property contents are discarded); dual stacked addresses are currently not supported.

The full JSON format for a BR data-plane AS-external underlay socket looks like the following:

{
  "Overlay": "UDP/IPv4",
  "ISD_AS": "1-ff00:0:1",
  "Bandwidth": 1000,
  "PublicOverlay": {
    "Addr": "192.168.0.1",
    "OverlayPort": 50000,
  },
  "BindOverlay": {
    "Addr": "127.0.0.1",
  },
  "RemoteOverlay": {
    "Addr": "192.168.0.2",
    "OverlayPort": 50000,
  },
  "LinkTo": "CORE",
  "MTU": 1472,
}

To construct a BR data-plane AS-external underlay socket address out of the above, the following rules are used:

• Properties "ISD_AS", "Bandwidth", "LinkTo", and "MTU" are ignored. All unknown properties not included in the above example are silently ignored.
• Properties "PublicOverlay" and "RemoteOverlay" must exist. An error is returned if one of them is missing.
• Property "BindOverlay" is optional. If it is not present, then the address checks below do not apply to property "Addr" under "BindOverlay". If it is present, the address is subject to all format constraints below.
• If property "Overlay" is "UDP/IPv4", all "Addr" properties are checked to be IPv4. If one cannot be parsed as an IPv4 address, an error is returned. If the address is the empty string, an error is returned.
• If property "Overlay" is "UDP/IPv6", all "Addr" properties are checked to be IPv6. If one cannot be parsed as an IPv6 address, an error is returned. If the address is the empty string, an error is returned.
• If a port property is missing, it is assumed to be 0. The application is free to interpret this however it sees fit.

The full JSON format for a BR data-plane AS-internal underlay socket address looks like the following:

{
  "IPv4": {
    "PublicOverlay": {
      "Addr": "192.168.0.1",
      "OverlayPort": 31000,
    },
    BindOverlay": {
      "Addr": "127.0.0.1"
    }
  },
  "IPv6": {
    "PublicOverlay": {
      "Addr": "2001:db8:f00:b43::1",
      "OverlayPort": 31000
    },
    "BindOverlay": {
      "Addr": "::1"
    }
  }
}

To construct a BR data-plane AS-internal underlay socket address out of the above, the following rules are used:

• Properties not listed in the above are ignored.
• If both property "IPv4" and "IPv6" are present, the address is assumed to be IPv6 and only that address is used (in other words, the IPv4 property contents are discarded); dual stacked addresses are currently not supported.
• For the chosen address, the underlay address is taken from the "BindOverlay" property; if this is the case, the "PublicOverlay" address is never parsed. The address must match the address type in the top-level property (IPv4 or IPv6), otherwise an error is returned. If the "BindOverlay" property does not exist, the underlay address is taken from the "PublicOverlay" property. The address must match the address type in the top-level property, otherwise an error is returned. No matter which address is used, the port is always taken from the "PublicOverlay" property". An unset port is interpreted as 0.

Index

• Constants
• type BRInfo
• type IDAddrMap
  • func (m IDAddrMap) GetByID(id string) *TopoAddr
• type IFInfo
  • func (i IFInfo) CheckLinks(isCore bool, brName string) error
  • func (i IFInfo) String() string
• type IfInfoMap
• type LinkType
  • func LinkTypeFromString(s string) LinkType
  • func (lt LinkType) String() string
• type Provider
• type RWTopology
  • func NewRWTopology() *RWTopology
  • func RWTopologyFromJSONBytes(b common.RawBytes) (*RWTopology, error)
  • func RWTopologyFromJSONFile(path string) (*RWTopology, error)
  • func RWTopologyFromJSONTopology(raw *jsontopo.Topology) (*RWTopology, error)
  • func (t *RWTopology) Active(now time.Time) bool
  • func (t *RWTopology) Expiry() time.Time
  • func (t *RWTopology) GetAllTopoAddrs(svc proto.ServiceType) ([]TopoAddr, error)
  • func (t *RWTopology) GetTopoAddr(id string, svc proto.ServiceType) (*TopoAddr, error)
• type ServiceNames
  • func (s ServiceNames) GetRandom() (string, error)
• type TopoAddr
  • func (a *TopoAddr) String() string
  • func (a *TopoAddr) UnderlayAddr() *net.UDPAddr
• type Topology
  • func FromJSONFile(path string) (Topology, error)
  • func FromRWTopology(topo *RWTopology) Topology
  • func NewTopology() Topology

Constants

const EndhostPort = overlay.EndhostPort

EndhostPort is the overlay port that the dispatcher binds to on non-routers.

Types

type BRInfo

type BRInfo struct {
	Name string
	// CtrlAddrs are the local control-plane addresses.
	CtrlAddrs *TopoAddr
	// InternalAddr is the local data-plane address.
	InternalAddr *net.UDPAddr
	// IFIDs is a sorted list of the interface IDs.
	IFIDs []common.IFIDType
	// IFs is a map of interface IDs.
	IFs map[common.IFIDType]*IFInfo
}

BRInfo is a list of AS-wide unique interface IDs for a router. These IDs are also used to point to the specific internal address clients should send their traffic to in order to use that interface, via the IFInfoMap member of the Topo struct.

type IDAddrMap

type IDAddrMap map[string]TopoAddr

IDAddrMap maps process IDs to their topology addresses.

func (IDAddrMap) GetByID

func (m IDAddrMap) GetByID(id string) *TopoAddr

GetByID returns the TopoAddr for the given ID, or nil if there is none.

type IFInfo

type IFInfo struct {
	// ID is the interface ID. It is unique per AS.
	ID           common.IFIDType
	BRName       string
	CtrlAddrs    *TopoAddr
	Underlay     overlay.Type
	InternalAddr *net.UDPAddr
	Local        *net.UDPAddr
	Remote       *net.UDPAddr
	RemoteIFID   common.IFIDType
	Bandwidth    int
	IA           addr.IA
	LinkType     LinkType
	MTU          int
}

IFInfo describes a border router link to another AS, including the internal data-plane address applications should send traffic to and information about the link itself and the remote side of it.

func (IFInfo) CheckLinks

func (i IFInfo) CheckLinks(isCore bool, brName string) error

CheckLinks checks whether the link types are compatible with whether the AS is core or not.

func (IFInfo) String

func (i IFInfo) String() string

type IfInfoMap

type IfInfoMap map[common.IFIDType]IFInfo

IfInfoMap maps interface ids to the interface information.

type LinkType

type LinkType int

LinkType describes inter-AS links.

const (
	// Unset is used for unknown link types.
	Unset LinkType = 0
	// Core links connect core ASes.
	Core LinkType = 1
	// Parent links are configured on non-core links pointing towards the core of an ISD.
	Parent LinkType = 2
	// Child links are configured on non-core links pointing away from the core of an ISD.
	Child LinkType = 3
	// Peer links are configured for peering relationships.
	Peer LinkType = 4
)

func LinkTypeFromString

func LinkTypeFromString(s string) LinkType

LinkTypeFromString returns the numerical link type associated with a string description. If the string is not recognized, an Unset link type is returned. The matching is case-insensitive.

func (LinkType) String

func (lt LinkType) String() string

type Provider

type Provider interface {
	// Get returns a topology. The returned topology is guaranteed to not be
	// nil.
	Get() Topology
}

Provider provides a topology snapshot. The snapshot is guaranteed to not change.

type RWTopology

type RWTopology struct {
	Timestamp  time.Time
	TTL        time.Duration
	IA         addr.IA
	Attributes trc.Attributes
	MTU        int

	BR        map[string]BRInfo
	BRNames   []string
	IFInfoMap IfInfoMap

	CS  IDAddrMap
	SIG IDAddrMap
}

RWTopology is the topology type for applications and libraries that need write access to AS topology information (e.g., discovery, topology reloaders).

The first section contains metadata about the topology. All of these fields should be self-explanatory. The unit of TTL is seconds, with the zero value indicating an infinite TTL.

The second section concerns the Border routers. BRNames is just a sorted slice of the names of the BRs in this topolgy. Its contents is exactly the same as the keys in the BR map.

The BR map points from border router names to BRInfo structs, which in turn are lists of IFID type slices, thus defines the IFIDs that belong to a particular border router. The IFInfoMap points from interface IDs to IFInfo structs.

The third section in RWTopology concerns the SCION-specific services in the topology. The structure is identical between the various elements. For each service, there is again a sorted slice of names of the servers that provide the service. Additionally, there is a map from those names to TopoAddr structs.

func NewRWTopology

func NewRWTopology() *RWTopology

NewRWTopology creates new empty Topo object, including all possible service maps etc.

func RWTopologyFromJSONBytes

func RWTopologyFromJSONBytes(b common.RawBytes) (*RWTopology, error)

RWTopologyFromJSONBytes extracts the topology from a JSON representation in raw byte format.

func RWTopologyFromJSONFile

func RWTopologyFromJSONFile(path string) (*RWTopology, error)

RWTopologyFromJSONFile extracts the topology from a file containing the JSON representation of the topology.

func RWTopologyFromJSONTopology

func RWTopologyFromJSONTopology(raw *jsontopo.Topology) (*RWTopology, error)

RWTopologyFromJSONTopology converts a parsed JSON struct topology to a topology usable by Go code.

func (*RWTopology) Active

func (t *RWTopology) Active(now time.Time) bool

Active returns whether the topology is active at the point in time specified by the argument. A topology is active if it is within a TTL window after the timestamp.

func (*RWTopology) Expiry

func (t *RWTopology) Expiry() time.Time

Expiry returns the expiration time of the topology. If TTL is zero, the zero value is returned.

func (*RWTopology) GetAllTopoAddrs

func (t *RWTopology) GetAllTopoAddrs(svc proto.ServiceType) ([]TopoAddr, error)

GetAllTopoAddrs returns the address information of all processes of the requested type.

func (*RWTopology) GetTopoAddr

func (t *RWTopology) GetTopoAddr(id string, svc proto.ServiceType) (*TopoAddr, error)

GetTopoAddr returns the address information for the process of the requested type with the requested ID.

type ServiceNames

type ServiceNames []string

ServiceNames is a slice of process names (e.g., "bs-1", "bs-2").

func (ServiceNames) GetRandom

func (s ServiceNames) GetRandom() (string, error)

GetRandom returns a random entry, or an error if the slice is empty.

type TopoAddr

type TopoAddr struct {
	SCIONAddress    *net.UDPAddr
	UnderlayAddress *net.UDPAddr
}

TopoAddr wraps the possible addresses of a SCION service and describes the underlay to be used for contacting said service.

func (*TopoAddr) String

func (a *TopoAddr) String() string

func (*TopoAddr) UnderlayAddr

func (a *TopoAddr) UnderlayAddr() *net.UDPAddr

UnderlayAddr returns the underlay address interpreted as a net.UDPAddr.

FIXME(scrye): This should be removed; applications should not need to look into the underlay concrete type.

type Topology

type Topology interface {
	// IA returns the local ISD-AS number.
	IA() addr.IA
	// MTU returns the MTU of the local AS.
	MTU() uint16
	// Core returns whether the local AS is core.
	Core() bool
	// InterfaceIDs returns all interface IDS from the local AS.
	InterfaceIDs() []common.IFIDType

	// PublicAddress gets the public address of a server with the requested type and name, and nil
	// if no such server exists.
	PublicAddress(svc addr.HostSVC, name string) *net.UDPAddr

	// Exists returns true if the service and name are present in the topology file.
	Exists(svc addr.HostSVC, name string) bool

	// SBRAddress returns the internal public address of the BR with the specified name.
	SBRAddress(name string) *snet.UDPAddr

	// Anycast returns the address for an arbitrary server of the requested type.
	Anycast(svc addr.HostSVC) (*net.TCPAddr, error)

	// OverlayAnycast returns the overlay address for an arbitrary server of the requested type.
	OverlayAnycast(svc addr.HostSVC) (*net.UDPAddr, error)
	// OverlayMulticast returns all overlay addresses for the requested type.
	OverlayMulticast(svc addr.HostSVC) ([]*net.UDPAddr, error)
	// OverlayByName returns the overlay address of the server name of the requested type.
	//
	// FIXME(scrye): This isn't really needed. We should also get rid of it.
	OverlayByName(svc addr.HostSVC, name string) (*net.UDPAddr, error)
	// OverlayNextHop2 returns the internal overlay address of the router containing the ID. The
	// return value is encoded as an overlay address.
	//
	// FIXME(scrye): Remove either this or the other method. A single return type should be
	// supported.
	OverlayNextHop2(ifID common.IFIDType) (*net.UDPAddr, bool)

	// OverlayNextHop returns the internal overlay address of the router
	// containing the interface ID.
	//
	// XXX(scrye): Return value is a shallow copy.
	OverlayNextHop(ifID common.IFIDType) (*net.UDPAddr, bool)

	// MakeHostInfos returns the overlay addresses of all services for the specified service type.
	MakeHostInfos(st proto.ServiceType) []net.UDPAddr

	// BR returns information for a specific border router
	//
	// FIXME(scrye): Simplify return type and make it topology format agnostic.
	//
	// XXX(scrye): Return value is a shallow copy.
	BR(name string) (BRInfo, bool)
	// IFInfoMap returns the mapping between interface IDs an internal addresses.
	//
	// FIXME(scrye): Simplify return type and make it topology format agnostic.
	//
	// XXX(scrye): Return value is a shallow copy.
	IFInfoMap() IfInfoMap

	// BRNames returns the names of all BRs in the topology.
	//
	// FIXME(scrye): Remove this, callers shouldn't care about names.
	//
	// XXX(scrye): Return value is a shallow copy.
	BRNames() []string

	// SVCNames returns the names of all servers in the topology for the specified service.
	//
	// FIXME(scrye): Remove this, callers shouldn't care about names.
	//
	// XXX(scrye): Return value is a shallow copy.
	SVCNames(svc addr.HostSVC) ServiceNames

	// Writable returns a pointer to the underlying topology object. This is included for legacy
	// reasons and should never be used.
	//
	// FIXME(scrye): Remove this.
	//
	// XXX(scrye): Return value is a shallow copy.
	Writable() *RWTopology
}

Topology is the topology type for applications and libraries that only need read access to AS topology information. This is the case of most applications and libraries that use the topology file to discover information about the local AS. Libraries that need to edit the topology (e.g., a topology reloading library that computes a new topology file based on information found on disk) should instead use the writable topology type present in this package.

func FromJSONFile

func FromJSONFile(path string) (Topology, error)

FromJSONFile extracts the topology from a file containing the JSON representation of the topology.

func FromRWTopology

func FromRWTopology(topo *RWTopology) Topology

FromRWTopology wraps the high level topology interface API around a raw topology object.

func NewTopology

func NewTopology() Topology

NewTopology creates a new empty topology.