sftp

package
v0.17.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 29 Imported by: 0

Documentation

Overview

Package sftp is Wings' built-in SFTP server (docs/WINGS.md#files-and-sftp). It's off by default and enabled per node. Users log in as user.serverid with a temporary password, which the Panel checks every time (nothing is cached, so logins fail while it's unreachable). Each session is confined to the server's directory with os.Root, and ends when the password runs out.

Index

Constants

View Source
const (
	PermSFTP  = "sftp"
	PermRead  = "files.read"
	PermWrite = "files.write"
)

Permissions a login needs (docs/PANEL.md#permissions): sftp to log in, files.read to read, files.write to change anything.

View Source
const EventLogin = "server.sftp.login"

EventLogin is recorded for every SFTP login, for the Panel's audit log.

View Source
const EventNode = "node.sftp"

EventNode is recorded whenever SFTP is turned on or off or moves to a new port, so the Panel shows the real port and the host key fingerprint.

Variables

View Source
var (
	// ErrDenied: the Panel rejected the login.
	ErrDenied = errors.New("login denied")
	// ErrUnavailable: the Panel couldn't be asked, so the login fails.
	ErrUnavailable = errors.New("panel unreachable")
)

Errors returned by an Authenticator.

Functions

func Fingerprint

func Fingerprint(k ssh.Signer) string

Fingerprint returns a host key's SHA-256 fingerprint as OpenSSH prints it.

func LoadHostKey

func LoadHostKey(path string) (ssh.Signer, error)

LoadHostKey reads the node's SSH host key, generating an Ed25519 key on first use. The key is created on the node and never leaves it; users check its fingerprint, which the Panel shows (docs/SECURITY-MODEL.md).

Types

type Authenticator

type Authenticator interface {
	Password(ctx context.Context, l Login, password string) (Grant, error)
}

Authenticator checks logins with the Panel over the node connection (Phase 3). Wings never stores passwords.

type Grant

type Grant struct {
	UserID      string   `json:"user_id"`
	Permissions []string `json:"permissions"`
	// ServerID is the server the login is for.
	ServerID string `json:"server_id"`
	// ExpiresAt ends the session (a temporary password's expiry); zero for
	// none.
	ExpiresAt time.Time `json:"-"`
}

Grant is what the Panel allows a login to do.

func (Grant) Has

func (g Grant) Has(perm string) bool

Has reports whether the grant includes a permission.

type Login

type Login struct {
	// Username is the login (t-…): the whole username, or the part before
	// the dot for the older user.serverid form.
	Username string
	// ServerID is the server the username named; empty when it named
	// none, until the Panel says which server the password is for.
	ServerID string
	Addr     netip.Addr
}

Login is who asked to log in, and to which server.

type Options

type Options struct {
	HostKey ssh.Signer
	Auth    Authenticator
	Servers Servers
	Events  *events.Outbox // nil: logins aren't recorded
	// UID and GID own what SFTP creates: the servers' user.
	UID, GID int
	Log      *slog.Logger
}

Options configure a Server.

type PanelAuth

type PanelAuth struct {
	// Panel returns a client while the node is connected, nil otherwise.
	Panel func() nodev1connect.PanelServiceClient
}

PanelAuth checks logins with the Panel over the node connection: the temporary passwords users turn on per server (docs/DECISIONS.md #222, #223). Accounts themselves have no passwords.

func (PanelAuth) Password

func (a PanelAuth) Password(ctx context.Context, l Login, password string) (Grant, error)

Password implements Authenticator. Passwords are only ever checked by the Panel: they aren't cached, so they don't work while it's unreachable.

type Server

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

Server accepts SFTP connections.

func New

func New(o Options) *Server

New returns a Server.

func (*Server) Close

func (s *Server) Close() error

Close stops listening, drops every connection, and waits for them.

func (*Server) Disconnect

func (s *Server) Disconnect(serverID string) int

Disconnect drops every connection to a server, e.g. when it's deleted or an install starts over its files. It returns how many were dropped.

func (*Server) DisconnectLogin added in v0.2.0

func (s *Server) DisconnectLogin(serverID, username string) int

DisconnectLogin drops one login's connections to a server, e.g. when its temporary password is revoked. It returns how many were dropped.

func (*Server) Serve

func (s *Server) Serve(ln net.Listener) error

Serve accepts connections on ln until Close. It returns nil after Close.

type Servers

type Servers interface {
	// Resolve returns the ID of the server a username names: its full ID
	// or its short ID.
	Resolve(ref string) (string, error)
	// FilesDir returns the server's directory.
	FilesDir(id string) (string, error)
	// CheckFiles returns an error while the server's files can't be read,
	// or written if write is set (installing, deleted, over the soft disk
	// limit).
	CheckFiles(ctx context.Context, id string, write bool) error
	// Denylist returns the file_denylist of the server's egg.
	Denylist(id string) ([]string, error)
}

Servers is what SFTP needs from the server manager.

type Service

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

Service runs the SFTP server while it's enabled for the node. Enabled is stored in SQLite and set by the Panel; SFTP is off by default.

func NewService

func NewService(o ServiceOptions) *Service

NewService returns a Service. Call Start to resume the stored state.

func (*Service) Close

func (s *Service) Close()

Close stops the server without changing the stored state.

func (*Service) Disconnect

func (s *Service) Disconnect(serverID string) int

Disconnect drops a server's connections.

func (*Service) DisconnectLogin added in v0.2.0

func (s *Service) DisconnectLogin(serverID, username string) int

DisconnectLogin drops one login's connections to a server.

func (*Service) SetEnabled

func (s *Service) SetEnabled(ctx context.Context, enabled bool) (Status, error)

SetEnabled turns SFTP on or off and stores the choice. Turning it on listens on the port it used last, else the preferred port, else the first free port in 2022–2099.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start turns SFTP on if it was enabled before Wings stopped.

func (*Service) Status

func (s *Service) Status() Status

Status returns the current state.

type ServiceOptions

type ServiceOptions struct {
	Options
	Store *store.DB
	// Port is the preferred port (ports.sftp in config.yml).
	Port int
	// Allocated returns ports allocated to servers, which SFTP never takes
	// even while those servers are stopped.
	Allocated func(context.Context) ([]int, error)
	// Listen opens the listener; net.Listen by default.
	Listen func(network, addr string) (net.Listener, error)
}

ServiceOptions configure a Service.

type Status

type Status struct {
	Enabled     bool   `json:"enabled"`
	Port        int    `json:"port,omitempty"` // 0 while off
	Fingerprint string `json:"host_key_fingerprint"`
}

Status is SFTP's state on the node.

Jump to

Keyboard shortcuts

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