peer

package
v0.83.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: BSD-3-Clause, AGPL-3.0 Imports: 12 Imported by: 21

Documentation

Index

Constants

View Source
const (
	PeerCapabilitySourcePrefixes      = nmdata.PeerCapabilitySourcePrefixes
	PeerCapabilityIPv6Overlay         = nmdata.PeerCapabilityIPv6Overlay
	PeerCapabilityComponentNetworkMap = nmdata.PeerCapabilityComponentNetworkMap
)

Peer capability constants mirror the proto enum values.

View Source
const InstanceHeartbeatInterval = time.Minute

InstanceHeartbeatInterval is how often a management instance refreshes its LastSeen.

View Source
const InstanceStaleAfter = 5 * time.Minute

InstanceStaleAfter is how long a management instance may go without a heartbeat before it counts as dead: the connections it holds read as disconnected and other instances sweep them. It spans several heartbeats so one missed refresh does not disconnect live peers.

Variables

This section is empty.

Functions

This section is empty.

Types

type Connection added in v0.83.0

type Connection struct {
	PeerID    string `gorm:"primaryKey"`
	AccountID string `gorm:"not null;index"`
	// InstanceID is the management instance holding the peer's sync stream, nil while no
	// instance holds it.
	InstanceID *string `gorm:"index"`
	// SessionStartedAt is the fencing token of the latest sync stream that held the peer,
	// in Unix nanoseconds. Releasing the connection regardless of its session advances it by
	// one, so the released session cannot be re-registered.
	SessionStartedAt int64 `gorm:"not null;default:0"`
	// LastSeen is the last time the peer was observed alive, apart from the heartbeat of
	// the instance holding it. Nil when it never was.
	LastSeen *time.Time
}

Connection is a peer's liveness record. It is created with the peer and lives until the peer is deleted. A peer counts as connected while InstanceID names a fresh management instance.

func (Connection) TableName added in v0.83.0

func (Connection) TableName() string

TableName returns the table that stores peer connections.

type Environment added in v0.26.3

type Environment struct {
	Cloud    string
	Platform string
}

Environment is a system environment information

type File added in v0.28.0

type File struct {
	Path             string
	Exist            bool
	ProcessIsRunning bool
}

File is a file on the system.

type Flags added in v0.47.0

type Flags struct {
	RosenpassEnabled    bool
	RosenpassPermissive bool
	ServerSSHAllowed    bool
	RemoteJobsAllowed   bool

	DisableClientRoutes bool
	DisableServerRoutes bool
	DisableDNS          bool
	DisableFirewall     bool
	BlockLANAccess      bool
	BlockInbound        bool
	DisableIPv6         bool

	LazyConnectionEnabled bool
}

Flags defines a set of options to control feature behavior

type Location added in v0.26.0

type Location struct {
	ConnectionIP net.IP `gorm:"serializer:json"` // from grpc peer or reverse proxy headers depends on setup
	CountryCode  string
	CityName     string
	GeoNameID    uint // city level geoname id
}

Location is a geo location information of a Peer based on public connection IP

type ManagementInstance added in v0.83.0

type ManagementInstance struct {
	// ID is random per process and never reused.
	ID string `gorm:"primaryKey"`
	// Hostname is informational.
	Hostname  string
	StartedAt time.Time `gorm:"not null;default:CURRENT_TIMESTAMP"`
	LastSeen  time.Time `gorm:"not null;default:CURRENT_TIMESTAMP"`
}

ManagementInstance is one running management process. Its LastSeen is written only with the database clock, so every comparison against it uses a single time source.

type MetaDiff added in v0.73.2

type MetaDiff struct {
	OldMeta     PeerSystemMeta
	NewMeta     PeerSystemMeta
	OldLocation Location
	NewLocation Location

	Changed []string
}

MetaDiff holds a peer's full before/after state across a sync: both metas and both connection locations (the location lives on Peer, not PeerSystemMeta, but posture checks read it). Changed lists what moved, for logging and the persistence decision; the snapshots let a posture check be replayed against old and new. Everything is derived from these fields, so there are no parallel per-field flags to keep in sync.

func (*MetaDiff) HostnameChanged added in v0.74.0

func (d *MetaDiff) HostnameChanged() bool

HostnameChanged reports whether the peer's hostname changed.

func (*MetaDiff) LogSummary added in v0.74.0

func (d *MetaDiff) LogSummary() string

LogSummary renders the changed fields as a single human-readable line.

func (*MetaDiff) Updated added in v0.73.2

func (d *MetaDiff) Updated() bool

Updated reports whether anything changed and the peer must be persisted. diffMeta fills Changed in the pass that builds the diff, so this is a length check, not a re-comparison. Pointer receiver: MetaDiff embeds two metas, so copying it per call is wasteful.

func (*MetaDiff) VersionChanged added in v0.73.2

func (d *MetaDiff) VersionChanged() bool

VersionChanged reports whether the WireGuard client version changed (a client upgrade).

type NetworkAddress added in v0.26.0

type NetworkAddress struct {
	NetIP netip.Prefix `gorm:"serializer:json"`
	Mac   string
}

NetworkAddress is the IP address with network and MAC address of a network interface

type Peer

type Peer struct {
	// ID is an internal ID of the peer
	ID string `gorm:"primaryKey"`
	// AccountID is a reference to Account that this object belongs
	AccountID string `json:"-" gorm:"index"`
	// WireGuard public key
	Key string // uniqueness index (check migrations)
	// IP address of the Peer
	IP netip.Addr `gorm:"serializer:json"` // uniqueness index per accountID (check migrations)
	// IPv6 overlay address of the Peer, zero value if IPv6 is not enabled for the account.
	IPv6 netip.Addr `gorm:"serializer:json"`
	// Meta is a Peer system meta data
	Meta PeerSystemMeta `gorm:"embedded;embeddedPrefix:meta_"`
	// ProxyMeta is metadata related to proxy peers
	ProxyMeta ProxyMeta `gorm:"embedded;embeddedPrefix:proxy_meta_"`
	// Name is peer's name (machine name)
	Name string `gorm:"index"`
	// DNSLabel is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's
	// domain to the peer label. e.g. peer-dns-label.netbird.cloud
	DNSLabel string // uniqueness index per accountID (check migrations)
	// Status peer's management connection status
	Status *PeerStatus `gorm:"embedded;embeddedPrefix:peer_status_"`
	// The user ID that registered the peer
	UserID string
	// SSHKey is a public SSH key of the peer
	SSHKey string
	// SSHEnabled indicates whether SSH server is enabled on the peer
	SSHEnabled bool
	// LoginExpirationEnabled indicates whether peer's login expiration is enabled and once expired the peer has to re-login.
	// Works with LastLogin
	LoginExpirationEnabled bool

	InactivityExpirationEnabled bool
	// LastLogin the time when peer performed last login operation
	LastLogin *time.Time
	// CreatedAt records the time the peer was created
	CreatedAt time.Time
	// Indicate ephemeral peer attribute
	Ephemeral bool `gorm:"index"`

	// Geo location based on connection IP
	Location Location `gorm:"embedded;embeddedPrefix:location_"`

	// ExtraDNSLabels is a list of additional DNS labels that can be used to resolve the peer
	ExtraDNSLabels []string `gorm:"serializer:json"`
	// AllowExtraDNSLabels indicates whether the peer allows extra DNS labels to be used for resolving the peer
	AllowExtraDNSLabels bool
}

Peer represents a machine connected to the network. The Peer is a WireGuard peer identified by a public key

func (*Peer) AddedWithSSOLogin

func (p *Peer) AddedWithSSOLogin() bool

AddedWithSSOLogin indicates whether this peer has been added with an SSO login by a user.

func (*Peer) Copy

func (p *Peer) Copy() *Peer

Copy copies Peer object

func (*Peer) EventMeta

func (p *Peer) EventMeta(dnsDomain string) map[string]any

EventMeta returns activity event meta related to the peer

func (*Peer) FQDN

func (p *Peer) FQDN(dnsDomain string) string

FQDN returns peers FQDN combined of the peer's DNS label and the system's DNS domain

func (*Peer) FromAPITemporaryAccessRequest added in v0.59.0

func (p *Peer) FromAPITemporaryAccessRequest(a *api.PeerTemporaryAccessRequest)

func (*Peer) GetLastLogin added in v0.36.0

func (p *Peer) GetLastLogin() time.Time

GetLastLogin returns the last login time of the peer.

func (*Peer) HasCapability added in v0.71.0

func (p *Peer) HasCapability(capability int32) bool

HasCapability reports whether the peer has the given capability.

func (*Peer) LoginExpired

func (p *Peer) LoginExpired(expiresIn time.Duration) (bool, time.Duration)

LoginExpired indicates whether the peer's login has expired or not. If Peer.LastLogin plus the expiresIn duration has happened already; then login has expired. Return true if a login has expired, false otherwise, and time left to expiration (negative when expired). Login expiration can be disabled/enabled on a Peer level via Peer.LoginExpirationEnabled property. Login expiration can also be disabled/enabled globally on the Account level via Settings.PeerLoginExpirationEnabled. Only peers added by interactive SSO login can be expired.

func (*Peer) MarkLoginExpired

func (p *Peer) MarkLoginExpired(expired bool)

MarkLoginExpired marks peer's status expired or not

func (*Peer) SessionExpired added in v0.30.2

func (p *Peer) SessionExpired(expiresIn time.Duration) (bool, time.Duration)

SessionExpired indicates whether the peer's session has expired or not. If Peer.LastLogin plus the expiresIn duration has happened already; then session has expired. Return true if a session has expired, false otherwise, and time left to expiration (negative when expired). Session expiration can be disabled/enabled on a Peer level via Peer.LoginExpirationEnabled property. Session expiration can also be disabled/enabled globally on the Account level via Settings.PeerLoginExpirationEnabled. Only peers added by interactive SSO login can be expired.

func (*Peer) SessionExpiresAt added in v0.72.0

func (p *Peer) SessionExpiresAt(accountExpirationEnabled bool, expiresIn time.Duration) time.Time

SessionExpiresAt returns the absolute UTC instant at which the peer's SSO session expires, derived from LastLogin and the account-level PeerLoginExpiration setting. Returns the zero value when login expiration does not apply (peer not SSO-registered, peer-level toggle off, or account expiry disabled). Callers should treat the zero value as "no deadline".

func (*Peer) SupportsComponentNetworkMap added in v0.75.0

func (p *Peer) SupportsComponentNetworkMap() bool

SupportsComponentNetworkMap reports whether the peer assembles its NetworkMap from server-shipped components instead of consuming a fully expanded NetworkMap. Determines whether the network_map controller skips Calculate() server-side and emits the components envelope.

func (*Peer) SupportsIPv6 added in v0.71.0

func (p *Peer) SupportsIPv6() bool

SupportsIPv6 reports whether the peer supports IPv6 overlay.

func (*Peer) SupportsSourcePrefixes added in v0.71.0

func (p *Peer) SupportsSourcePrefixes() bool

SupportsSourcePrefixes reports whether the peer reads SourcePrefixes.

func (*Peer) UpdateLastLogin

func (p *Peer) UpdateLastLogin() *Peer

UpdateLastLogin and set login expired false

func (*Peer) UpdateMetaIfNew

func (p *Peer) UpdateMetaIfNew(ctx context.Context, meta PeerSystemMeta, newLocation *Location) MetaDiff

UpdateMetaIfNew updates peer's system metadata and connection geo location if new information is provided. newLocation is the geo location resolved from the peer's current connection IP, or nil when there is nothing to apply (geo disabled, no real IP, or the IP is unchanged); the caller owns the expensive lookup and the same-IP guard. It returns a MetaDiff describing what changed; diff.Updated() reports whether the peer needs to be persisted.

type PeerStatus

type PeerStatus struct {
	// LastSeen is the last time the peer was observed alive: the later of the peer's own
	// connection record and the heartbeat of the instance holding its connection. It is
	// derived from the connection record; the peer_status_last_seen column is deprecated
	// and neither read nor written.
	LastSeen time.Time `gorm:"-"`
	// SessionStartedAt is the fencing token of the latest sync stream that held the peer's
	// connection, in Unix nanoseconds, zero when none did. It is derived from the
	// connection record; the peer_status_session_started_at column is deprecated and
	// neither read nor written.
	SessionStartedAt int64 `gorm:"-"`
	// Connected indicates whether peer is connected to the management service or not.
	// It is derived from the connection record; the peer_status_connected column is
	// deprecated and neither read nor written.
	Connected bool `gorm:"-"`
	// LoginExpired
	LoginExpired bool
	// RequiresApproval indicates whether peer requires approval or not
	RequiresApproval bool
}

func (*PeerStatus) ApplyConnection added in v0.83.0

func (s *PeerStatus) ApplyConnection(session sql.NullInt64, lastSeen, instanceLastSeen sql.NullTime)

ApplyConnection derives Connected, LastSeen and SessionStartedAt from the peer's connection record: its session token, its own LastSeen, and the LastSeen of the instance holding the connection. Each is invalid when the record, or the instance, is missing. A peer is connected only while an instance that heartbeated within InstanceStaleAfter holds it. LastSeen is the later of the record's and the instance's.

func (*PeerStatus) Copy

func (p *PeerStatus) Copy() *PeerStatus

Copy returns a copy of the PeerStatus.

type PeerSystemMeta

type PeerSystemMeta struct {
	Hostname           string
	GoOS               string
	Kernel             string
	Core               string
	Platform           string
	OS                 string
	OSVersion          string
	WtVersion          string
	UIVersion          string
	KernelVersion      string
	NetworkAddresses   []NetworkAddress `gorm:"serializer:json"`
	SystemSerialNumber string
	SystemProductName  string
	SystemManufacturer string
	Environment        Environment `gorm:"serializer:json"`
	Flags              Flags       `gorm:"serializer:json"`
	Files              []File      `gorm:"serializer:json"`
	Certificates       []string    `gorm:"serializer:json"`
	Capabilities       []int32     `gorm:"serializer:json"`
	SyncMessageVersion int
}

PeerSystemMeta is a metadata of a Peer machine system

type ProxyMeta added in v0.65.0

type ProxyMeta struct {
	Embedded bool   `gorm:"index"`
	Cluster  string `gorm:"index"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL