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
- Variables
- func Fingerprint(k ssh.Signer) string
- func LoadHostKey(path string) (ssh.Signer, error)
- type Authenticator
- type Grant
- type Login
- type Options
- type PanelAuth
- type Server
- type Servers
- type Service
- func (s *Service) Close()
- func (s *Service) Disconnect(serverID string) int
- func (s *Service) DisconnectLogin(serverID, username string) int
- func (s *Service) SetEnabled(ctx context.Context, enabled bool) (Status, error)
- func (s *Service) Start(ctx context.Context) error
- func (s *Service) Status() Status
- type ServiceOptions
- type Status
Constants ¶
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.
const EventLogin = "server.sftp.login"
EventLogin is recorded for every SFTP login, for the Panel's audit log.
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 ¶
var ( // ErrDenied: the Panel rejected the login. ErrDenied = errors.New("login denied") ErrUnavailable = errors.New("panel unreachable") )
Errors returned by an Authenticator.
Functions ¶
func Fingerprint ¶
Fingerprint returns a host key's SHA-256 fingerprint as OpenSSH prints it.
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.
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.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server accepts SFTP connections.
func (*Server) Disconnect ¶
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
DisconnectLogin drops one login's connections to a server, e.g. when its temporary password is revoked. It returns how many were dropped.
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 ¶
Disconnect drops a server's connections.
func (*Service) DisconnectLogin ¶ added in v0.2.0
DisconnectLogin drops one login's connections to a server.
func (*Service) SetEnabled ¶
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.
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.