Help us shape the future of Go! Take the 2026 Go Developer Survey

server

package
v0.81.3 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: BSD-3-Clause Imports: 41 Imported by: 0

Documentation

Overview

Package server implements port forwarding for the SSH server.

Security note: Port forwarding runs in the main server process without privilege separation. The attack surface is primarily io.Copy through well-tested standard library code, making it lower risk than shell execution which uses privilege-separated child processes. We enforce user-level port restrictions: non-privileged users cannot bind to ports < 1024.

Index

Constants

View Source 
const (
	ExitCodeSuccess           = 0
	ExitCodePrivilegeDropFail = 10
	ExitCodeShellExecFail     = 11
	ExitCodeValidationFail    = 12
)

Exit codes for executor process communication

View Source 
const (
	// FeatureSSHLogin represents SSH login operations for privilege checking
	FeatureSSHLogin = "SSH login"
	// FeatureSFTP represents SFTP operations for privilege checking
	FeatureSFTP = "SFTP"
)
View Source 
const (

	// DefaultJWTMaxTokenAge is the default maximum age for JWT tokens accepted by the SSH server.
	// Set to 10 minutes to accommodate identity providers like Azure Entra ID
	// that backdate the iat claim by up to 5 minutes.
	DefaultJWTMaxTokenAge = 10 * 60
)
View Source 
const DefaultSSHPort = 22

DefaultSSHPort is the default SSH port of the NetBird's embedded SSH server

View Source 
const InternalSSHPort = 22022

InternalSSHPort is the port SSH server listens on and is redirected to

Variables

View Source 
var (
	ErrPrivilegedUserDisabled = errors.New(msgPrivilegedUserDisabled)
	ErrUserNotFound           = errors.New("user not found")
)
View Source 
var (
	ErrPrivilegeRequired    = errors.New("SeAssignPrimaryTokenPrivilege required for user switching - NetBird must run with elevated privileges")
	ErrPrivilegedUserSwitch = errors.New("cannot switch to privileged user - current user lacks required privileges")
)

Functions

func StartTestServer 

func StartTestServer(t *testing.T, server *Server) string

StartTestServer starts the SSH server and returns the address it's listening on.

Types

type Config 

type Config struct {
	// JWT authentication configuration. If nil, JWT authentication is disabled
	JWT *JWTConfig

	// HostKey is the SSH server host key in PEM format
	HostKeyPEM []byte

	// Auth is the fine-grained authorization to open with. Nil starts with an
	// empty authorizer, which authorizes nobody until UpdateSSHAuth is called.
	// Setting it here rather than afterwards means the server never accepts a
	// login before it knows who is allowed.
	Auth *sshauth.Config
}

Config contains all SSH server configuration options

type ExecutorConfig 

type ExecutorConfig struct {
	UID        uint32
	GID        uint32
	Groups     []uint32
	WorkingDir string
	Shell      string
	Command    string
	PTY        bool
}

ExecutorConfig holds configuration for the executor process

type JWTConfig 

type JWTConfig struct {
	Issuer       string
	KeysLocation string
	MaxTokenAge  int64
	Audiences    []string
}

type PrivilegeCheckRequest 

type PrivilegeCheckRequest struct {
	// Username being requested (empty = current user)
	RequestedUsername         string
	FeatureSupportsUserSwitch bool // Does this feature/operation support user switching?
	FeatureName               string
}

PrivilegeCheckRequest represents a privilege check request

type PrivilegeCheckResult 

type PrivilegeCheckResult struct {
	// Allowed indicates whether the privilege check passed
	Allowed bool
	// User is the effective user to use for the operation (nil if not allowed)
	User *user.User
	// Error contains the reason for denial (nil if allowed)
	Error error
	// UsedFallback indicates we fell back to current user instead of requested user.
	// This happens on Unix when running as an unprivileged user (e.g., in containers)
	// where there's no point in user switching since we lack privileges anyway.
	// When true, all privilege checks have already been performed and no additional
	// privilege dropping or root checks are needed - the current user is the target.
	UsedFallback bool
	// RequiresUserSwitching indicates whether user switching will actually occur
	// (false for fallback cases where no actual switching happens)
	RequiresUserSwitching bool
}

PrivilegeCheckResult represents the result of a privilege check

type PrivilegeDropper 

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

PrivilegeDropper handles secure privilege dropping in child processes

func NewPrivilegeDropper 

func NewPrivilegeDropper(opts ...PrivilegeDropperOption) *PrivilegeDropper

NewPrivilegeDropper creates a new privilege dropper

func (*PrivilegeDropper) CreateExecutorCommand 

func (pd *PrivilegeDropper) CreateExecutorCommand(ctx context.Context, config ExecutorConfig) (*exec.Cmd, error)

CreateExecutorCommand creates a command that spawns netbird ssh exec for privilege dropping

func (*PrivilegeDropper) DropPrivileges 

func (pd *PrivilegeDropper) DropPrivileges(targetUID, targetGID uint32, supplementaryGroups []uint32) error

DropPrivileges performs privilege dropping with thread locking for security

func (*PrivilegeDropper) ExecuteWithPrivilegeDrop 

func (pd *PrivilegeDropper) ExecuteWithPrivilegeDrop(ctx context.Context, config ExecutorConfig)

ExecuteWithPrivilegeDrop executes a command with privilege dropping, using exit codes to signal specific failures

type PrivilegeDropperOption added in v0.64.2 

type PrivilegeDropperOption func(*PrivilegeDropper)

PrivilegeDropperOption is a functional option for configuring PrivilegeDropper

func WithLogger added in v0.64.2 

func WithLogger(logger *log.Entry) PrivilegeDropperOption

WithLogger sets the logger for the PrivilegeDropper

type PrivilegedUserError 

type PrivilegedUserError struct {
	Username string
}

PrivilegedUserError represents an error when privileged user login is disabled

func (*PrivilegedUserError) Error 

func (e *PrivilegedUserError) Error() string

func (*PrivilegedUserError) Is 

func (e *PrivilegedUserError) Is(target error) bool

type Server 

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

func New 

func New(config *Config) *Server

New creates an SSH server instance with the provided host key and optional JWT configuration If jwtConfig is nil, JWT authentication is disabled

func (*Server) AddListener added in v0.71.0 

func (s *Server) AddListener(ctx context.Context, addr netip.AddrPort) error

AddListener starts serving SSH on an additional address (e.g. IPv6). Must be called after Start.

func (*Server) Addr added in v0.62.0 

func (s *Server) Addr() net.Addr

Addr returns the address the SSH server is listening on, or nil if the server is not running

func (*Server) AuthConfig added in v0.78.0 

func (s *Server) AuthConfig() *sshauth.Config

AuthConfig returns the fine-grained authorization currently in force, or nil when the server has no authorizer.

func (*Server) CheckPrivileges 

func (s *Server) CheckPrivileges(req PrivilegeCheckRequest) PrivilegeCheckResult

CheckPrivileges performs comprehensive privilege checking for all SSH features. This is the single source of truth for privilege decisions across the SSH server.

func (*Server) GetStatus 

func (s *Server) GetStatus() (enabled bool, sessions []SessionInfo)

GetStatus returns the current status of the SSH server and active sessions.

func (*Server) JWTConfig added in v0.78.0 

func (s *Server) JWTConfig() *JWTConfig

JWTConfig returns the JWT authentication this server was built with, or nil when JWT authentication is disabled.

func (*Server) SetAllowLocalPortForwarding 

func (s *Server) SetAllowLocalPortForwarding(allow bool)

SetAllowLocalPortForwarding configures local port forwarding

func (*Server) SetAllowRemotePortForwarding 

func (s *Server) SetAllowRemotePortForwarding(allow bool)

SetAllowRemotePortForwarding configures remote port forwarding

func (*Server) SetAllowRootLogin 

func (s *Server) SetAllowRootLogin(allow bool)

SetAllowRootLogin configures root login access

func (*Server) SetAllowSFTP 

func (s *Server) SetAllowSFTP(allow bool)

SetAllowSFTP enables or disables SFTP support

func (*Server) SetNetstackNet 

func (s *Server) SetNetstackNet(net *netstack.Net)

SetNetstackNet sets the netstack network for userspace networking

func (*Server) SetNetworkValidation 

func (s *Server) SetNetworkValidation(addr wgaddr.Address)

SetNetworkValidation configures network-based connection filtering

func (*Server) Start 

func (s *Server) Start(ctx context.Context, addr netip.AddrPort) error

Start runs the SSH server

func (*Server) Stop 

func (s *Server) Stop() error

Stop closes the SSH server

func (*Server) UpdateSSHAuth added in v0.61.0 

func (s *Server) UpdateSSHAuth(config *sshauth.Config)

UpdateSSHAuth updates the SSH fine-grained access control configuration This should be called when network map updates include new SSH auth configuration

type SessionInfo 

type SessionInfo struct {
	Username      string
	RemoteAddress string
	Command       string
	JWTUsername   string
	PortForwards  []string
}

SessionInfo contains information about an active SSH session

type UserNotFoundError 

type UserNotFoundError struct {
	Username string
	Cause    error
}

UserNotFoundError represents an error when a user cannot be found

func (*UserNotFoundError) Error 

func (e *UserNotFoundError) Error() string

func (*UserNotFoundError) Is 

func (e *UserNotFoundError) Is(target error) bool

func (*UserNotFoundError) Unwrap 

func (e *UserNotFoundError) Unwrap() error

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.