relaydaemon

README

libp2p-relay-daemon

A standalone daemon that provides libp2p circuit relay services, for both protocol versions v1 and v2.

• Installation
  • Running as a systemd service
• Identity
• Configuration
  • Minimal config file
  • All configuration options
• Release process

Installation

To install the latest release:

go install github.com/ourzora/go-libp2p-relay-daemon/cmd/libp2p-relay-daemon@latest

The above will install libp2p-relay-daemon binary in GOBIN which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH is not set.

Development

To build from local sources:

git clone git@github.com:libp2p/go-libp2p-relay-daemon.git
cd go-libp2p-relay-daemon
go install ./...

Running as a systemd service

There is a service file and an associated launch script in etc. These two assume that you have installed as root [in your container]. If your installation path differs, adjust accordingly.

Identity

The daemon creates and persists an identity in the first run, using identity as the file to store the private key for the identity. You can specify the identity file path with the -identity option.

Private Swarms

The daemon can be instantiated using a multicodec-encoded V1 Private Swarm Key using the -swarmkey argument. Simply provide a filepath to the PSK and the daemon will automatically configure itself to use this for connections. Note that this limits the daemon to only use PSK-supported protocols, excluding QUIC and WebTransport as options.

Configuration

libp2p-relay-daemon accepts a -config option that specifies its configuration; if omitted it will use the defaults from cmd/libp2p-relay-daemon/config.go. Any field omitted from the configuration will retain its default value.

Minimal config file

Below JSON config ensures only the circuit relay v2 is provided on custom ports:

{
  "RelayV2": {
    "Enabled": true
  },
  "Network": {
    "ListenAddrs": [
        "/ip4/0.0.0.0/udp/4002/quic",
        "/ip6/::/udp/4002/quic",
        "/ip4/0.0.0.0/tcp/4002",
        "/ip6/::/tcp/4002",
        "/ip4/0.0.0.0/tcp/4003/ws",
        "/ip6/::/tcp/4003/ws"
    ]
  },
  "Daemon": {
    "PprofPort": 6061
  }
}

All configuration options

The configuration struct is as following (with defaults noted):

// libp2p-relay-daemon Configuration
type Config struct {
    Network NetworkConfig
    ConnMgr ConnMgrConfig
    RelayV2 RelayV2Config
    ACL     ACLConfig
    Daemon  DaemonConfig
}

// General daemon options
type DaemonConfig struct {
    // pprof port; default is 6060 (-1 disables pprof)
    PprofPort int
}

// Networking configuration
type NetworkConfig struct {
    // Addresses to listen on, as multiaddrs.
    // Default:
    //  [
    //    "/ip4/0.0.0.0/udp/4001/quic",
    //    "/ip6/::/udp/4001/quic",
    //    "/ip4/0.0.0.0/tcp/4001",
    //    "/ip6/::/tcp/4001",
    //  ]
    ListenAddrs   []string

    // Address to announce to the network, as multiaddrs.
    // Default is empty, which announces all public listen addresses to the network.
    AnnounceAddrs []string
}

// Connection Manager configuration
type ConnMgrConfig struct {
    // Connection low water mark; default is 512
    ConnMgrLo    int

    // Connection high water mark; default is 768
    ConnMgrHi    int

    // Connection grace period; default is 2 minutes
    ConnMgrGrace time.Duration
}

// Circuit Relay v2 support
type RelayV2Config struct {
    // whther to enable v2 relay; default is true
    Enabled   bool

    // relayv2 resource limits; see below
    Resources relayv2.Resources
}

// Access Control Lists
type ACLConfig struct {
    // List of peer IDs to allow reservations (v2) or hops to (v1).
    // If empty, then the relay is open and will allow reservations/relaying for any peer.
    // Default is empty.
    AllowPeers   []string

    // List of (CIDR) subnets to allow reservations (v2) or hops to (v1).
    // If empty, then the relay is open and will allow reservations/relaying for any network.
    // Default is empty
    AllowSubnets []string
}

Relay v1 Resource Limits

// Rsources are the resource limits associated with the v1 relay service
type Resources struct {
    // MaxCircuits is the maximum number of active relay connections.
    // Default is 1024.
    MaxCircuits int

    // MaxCircuitsPerPeer is the maximum number of active relay connections per peer
    // Default is 64.
    MaxCircuitsPerPeer int

    // BufferSize is the buffer size for relaying in each direction.
    // Default is 4096
    BufferSize int
}

Relay v2 Resource Limits

// Resources are the resource limits associated with the v2 relay service.
type Resources struct {
    // Limit is the (optional) relayed connection limits.
    Limit *RelayLimit

    // ReservationTTL is the duration of a new (or refreshed reservation).
    // Defaults to 1hr.
    ReservationTTL time.Duration

    // MaxReservations is the maximum number of active relay slots; defaults to 128.
    MaxReservations int

    // MaxCircuits is the maximum number of open relay connections for each peer; defaults to 16.
    MaxCircuits int

    // BufferSize is the size of the relayed connection buffers; defaults to 2048.
    BufferSize int

    // MaxReservationsPerPeer is the maximum number of reservations originating from the same
    // peer; default is 4.
    MaxReservationsPerPeer int

    // MaxReservationsPerIP is the maximum number of reservations originating from the same
    // IP address; default is 8.
    MaxReservationsPerIP int

    // MaxReservationsPerASN is the maximum number of reservations origination from the same
    // ASN; default is 32
    MaxReservationsPerASN int
}

// RelayLimit are the per relayed connection resource limits.
type RelayLimit struct {
    // Duration is the time limit before resetting a relayed connection; defaults to 2min.
    Duration time.Duration

    // Data is the limit of data relayed (on each direction) before resetting the connection.
    // Defaults to 128KB
    Data int64
}

Release Process

1. Bump version in version.json and wait for CI to create a tag in this repo
2. Follow ipfs/distributions#adding-a-version, wait for master branch there to finish and add new version to /ipns/dist.ipfs.io/libp2p-relay-daemon/
3. Back to this repo, create Github Release, and attach artifacts from /ipns/dist.ipfs.io/libp2p-relay-daemon/{version}

License

© vyzo; MIT License.

Documentation

Index

• func GenerateIdentity(path string) (crypto.PrivKey, error)
• func LoadIdentity(idPath string) (crypto.PrivKey, error)
• func ReadIdentity(path string) (crypto.PrivKey, error)
• type ACLConfig
• type ACLFilter
  • func NewACL(h host.Host, cfg ACLConfig) (*ACLFilter, error)
  • func (a *ACLFilter) AllowConnect(src peer.ID, srcAddr ma.Multiaddr, dest peer.ID) bool
  • func (a *ACLFilter) AllowHop(src, dest peer.ID) bool
  • func (a *ACLFilter) AllowReserve(p peer.ID, addr ma.Multiaddr) bool
  • func (a *ACLFilter) Connected(n network.Network, c network.Conn)
  • func (a *ACLFilter) Disconnected(n network.Network, c network.Conn)
• type Config
  • func DefaultConfig() Config
  • func LoadConfig(cfgPath string) (Config, error)
• type ConnMgrConfig
• type DaemonConfig
• type NetworkConfig
• type PNetFingerprint
  • func LoadSwarmKey(path string) (pnet.PSK, PNetFingerprint, error)
• type RelayV2Config

Functions

func GenerateIdentity

func GenerateIdentity(path string) (crypto.PrivKey, error)

GenerateIdentity writes a new random private key to the given path.

func LoadIdentity

func LoadIdentity(idPath string) (crypto.PrivKey, error)

LoadIdentity reads a private key from the given path and, if it does not exist, generates a new one.

func ReadIdentity

func ReadIdentity(path string) (crypto.PrivKey, error)

ReadIdentity reads a private key from the given path.

Types

type ACLConfig

type ACLConfig struct {
	AllowPeers   []string
	AllowSubnets []string
}

ACLConfig provides filtering configuration to allow specific peers or subnets to be fronted by relays. In V2, this specifies the peers/subnets that are able to make reservations on the relay. In V1, this specifies the peers/subnets that can be contacted through the relays.

type ACLFilter

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

ACLFilter implements the libp2p relay ACL interface.

func NewACL

func NewACL(h host.Host, cfg ACLConfig) (*ACLFilter, error)

NewACL returns an implementation of the relay ACL interface using the given host and relay daemon ACL config.

func (*ACLFilter) AllowConnect

func (a *ACLFilter) AllowConnect(src peer.ID, srcAddr ma.Multiaddr, dest peer.ID) bool

AllowConnect is always true, as we are accepting any public node to be able to contact the nodes allowed to make reservations through this relay.

func (*ACLFilter) AllowHop

func (a *ACLFilter) AllowHop(src, dest peer.ID) bool

AllowHop is relevant for relayv1 ACL implementation.

func (*ACLFilter) AllowReserve

func (a *ACLFilter) AllowReserve(p peer.ID, addr ma.Multiaddr) bool

AllowReserve is relevant for the relayv2 ACL implementation.

func (*ACLFilter) Connected

func (a *ACLFilter) Connected(n network.Network, c network.Conn)

Connected handles the Connect notification and stores the address of the connected node so that the ACL can decide whether other nodes can connect to it (relayV1).

func (*ACLFilter) Disconnected

func (a *ACLFilter) Disconnected(n network.Network, c network.Conn)

Disconnected handles the Disconnect notification and deletes the address of the disconnected node.

type Config

type Config struct {
	Network NetworkConfig
	ConnMgr ConnMgrConfig
	RelayV2 RelayV2Config
	ACL     ACLConfig
	Daemon  DaemonConfig
}

Config stores the full configuration of the relays, ACLs and other settings that influence behaviour of a relay daemon.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a default relay configuration using default resource settings and no ACLs.

func LoadConfig

func LoadConfig(cfgPath string) (Config, error)

LoadConfig reads a relay daemon JSON configuration from the given path. The configuration is first initialized with DefaultConfig, so all unset fields will take defaults from there.

type ConnMgrConfig

type ConnMgrConfig struct {
	ConnMgrLo    int
	ConnMgrHi    int
	ConnMgrGrace time.Duration
}

ConnMgrConfig controls the libp2p connection manager settings.

type DaemonConfig

type DaemonConfig struct {
	PprofPort int
}

DaemonConfig controls settings for the relay-daemon itself.

type NetworkConfig

type NetworkConfig struct {
	ListenAddrs   []string
	AnnounceAddrs []string
}

NetworkConfig controls listen and annouce settings for the libp2p host.

type PNetFingerprint

type PNetFingerprint []byte

func LoadSwarmKey

func LoadSwarmKey(path string) (pnet.PSK, PNetFingerprint, error)

LoadSwarmKey loads a swarm key at the given filepath and decodes it as a PSKv1.

type RelayV2Config

type RelayV2Config struct {
	Enabled   bool
	Resources relayv2.Resources
}

RelayV2Config controls activation of V2 circuits and resouce configuration for them.