Documentation
¶
Overview ¶
Package sftp is tommy's SFTP listener: a files provider that owns a real SSH port and writes everything uploaded to it into the plugin's shared virtual filesystem.
SFTP is an SSH subsystem rather than FTP with TLS bolted on, so this provider runs two layers: an x/crypto/ssh transport that performs the handshake, records whatever credentials were presented and honors a request for the "sftp" subsystem, and a pkg/sftp RequestServer whose four handlers are backed by a files.Session. Nothing is ever written to the host filesystem - the one file this provider owns on disk is its SSH host key, which must survive a restart or every client fails with a changed-host-key error.
Index ¶
- Constants
- func DefaultHostKeyPath() string
- func ExpandPath(p string) string
- type Config
- type HostKey
- type Provider
- func (p *Provider) Addr(timeout time.Duration) (string, error)
- func (p *Provider) BindVFS(v *files.VFS)
- func (p *Provider) Description() string
- func (p *Provider) Endpoints() []plugin.Endpoint
- func (p *Provider) HostKey() HostKey
- func (p *Provider) Listen(ctx context.Context, d plugin.Deps) error
- func (p *Provider) ListenPort(pc plugin.ProviderConfig) plugin.ListenPort
- func (p *Provider) Name() string
- func (p *Provider) Plugin() string
- func (p *Provider) RegisterIngress(mux plugin.Mux, d plugin.Deps)
- func (p *Provider) Snippets() []plugin.Snippet
Constants ¶
const ( DefaultBind = "127.0.0.1" // DefaultHostKeyName is the file name under the user config directory. DefaultHostKeyName = "sftp_host_ed25519" // DefaultServerVersion is the identification string sent before the // handshake. It must start with "SSH-2.0-" to be a legal SSH banner. DefaultServerVersion = "SSH-2.0-tommy" // DefaultHandshakeTimeout bounds the time between accepting a connection // and completing authentication, so a client that connects and says // nothing cannot hold a slot forever. DefaultHandshakeTimeout = 30 * time.Second // DefaultIdleTimeout drops a connection that has neither read nor written // for this long. Uploads refresh it as they go, so a slow transfer is // never cut off. DefaultIdleTimeout = 10 * time.Minute // DefaultMaxConnections caps concurrent SSH connections. DefaultMaxConnections = 64 // DefaultMaxAuthTries caps authentication attempts per connection. DefaultMaxAuthTries = 6 )
Defaults for the rest of the listener.
const DefaultPort = 2222
DefaultPort is the port the listener binds when the configuration says nothing. 2222 is the unprivileged SSH convention, and it stays clear of a real sshd on 22.
const ProviderName = "sftp"
ProviderName is the provider's name, which is also how it is addressed in configuration: [plugins.files.providers.sftp].
Variables ¶
This section is empty.
Functions ¶
func DefaultHostKeyPath ¶
func DefaultHostKeyPath() string
DefaultHostKeyPath is where the key lives when the configuration says nothing: alongside whatever else tommy keeps in the user's config directory. It falls back to the temporary directory only when there is no config directory at all (no HOME), because a key that cannot be written anywhere is a key that changes on every restart - the exact failure this file exists to prevent.
func ExpandPath ¶
ExpandPath resolves a leading ~ against the user's home directory, which is how the path is written in tommy.toml. Anything else is returned untouched, including a relative path: the process working directory is a legitimate place to keep a throwaway key.
Types ¶
type Config ¶
type Config struct {
Bind string
Port int
// HostKeyPath is where the ed25519 host key is kept. It is generated on
// first use and read back on every later run: an SSH server that changes
// its identity between restarts breaks every client that remembered it.
HostKeyPath string
// AuthorizedKeysPath, when set, is an OpenSSH authorized_keys file that
// public-key authentication is checked against. Unset means any key is
// accepted, and only recorded.
AuthorizedKeysPath string
// Username and Password pin the credentials the listener accepts. They are
// empty by default, which means anyone gets in - with a password, with a
// key, or with no credentials at all - and what they presented is recorded.
// Set either one and a password becomes mandatory and is checked, which is
// how you exercise your application's error path.
Username string
Password string
ServerVersion string
HandshakeTimeout time.Duration
IdleTimeout time.Duration
MaxConnections int
MaxAuthTries int
}
Config is the [plugins.files.providers.sftp] section.
Every key is optional. port = 0 means "bind an ephemeral port", which is what the test harness uses; an absent port means DefaultPort.
func LoadConfig ¶
func LoadConfig(pc plugin.ProviderConfig) Config
LoadConfig reads the provider section, applying every default.
func (Config) ListenAddr ¶
ListenAddr is the address Listen binds.
func (Config) RequiresAuth ¶
RequiresAuth reports whether the configuration pins credentials. When it does not, anything a client offers is accepted and recorded but never demanded.
type HostKey ¶
type HostKey struct {
Signer ssh.Signer
// Path is the file the key lives in.
Path string
// Created is true when this run generated the key rather than loading it.
Created bool
}
HostKey is a loaded SSH host key together with where it came from.
The whole point of this type is the Created flag and the Fingerprint: an SSH client remembers the key of every host it has ever talked to, so a server that generates a fresh one on each boot makes every second connection fail with the alarming REMOTE HOST IDENTIFICATION HAS CHANGED banner - and the person debugging it blames tommy, not their known_hosts file. The key is therefore written to disk on first use and read back forever after, and the fingerprint is logged at startup so it can be compared against what the client reports.
func LoadOrCreateHostKey ¶
LoadOrCreateHostKey returns the host key at path, generating and persisting a new ed25519 key the first time.
The file is created with 0600 through O_EXCL, so two tommys racing on the same path end up agreeing on one key rather than overwriting each other, and the key is never left world-readable. A missing parent directory is created with 0700.
A file that exists but cannot be parsed is an error naming the path rather than a silent regeneration: replacing a key the clients already trust is exactly the outcome that must never happen by accident.
func (HostKey) AuthorizedKey ¶
AuthorizedKey is the key's public half in authorized_keys form, which is what goes into a known_hosts entry.
func (HostKey) Fingerprint ¶
Fingerprint is the SHA256 fingerprint OpenSSH prints, in the same form, so a line from the log can be compared with what the client showed.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is the SFTP listener.
func New ¶
func New() *Provider
New returns the SFTP provider. Everything it needs - the port, the host key path, the shared filesystem - arrives later, so one value is safe to construct before anything is running.
func (*Provider) Addr ¶
Addr blocks until the listener is bound and returns its address, which is how a test finds the ephemeral port it asked for. The channel is created in New, so Addr and Listen never race.
func (*Provider) BindVFS ¶
BindVFS implements files.VFSBinder: the plugin hands every provider the one tree they all write into, so a file uploaded over SFTP is listed over FTP and downloadable from the Files tab.
func (*Provider) Description ¶
Description implements plugin.Provider.
func (*Provider) Endpoints ¶
Endpoints implements plugin.Provider. The provider speaks SSH on its own port and mounts no HTTP routes.
func (*Provider) HostKey ¶
HostKey reports the key the running listener presents, once it has bound. It is empty before that; Addr is the way to wait.
func (*Provider) Listen ¶
Listen implements plugin.ListenerProvider. It loads or generates the host key, binds the port from d.Config, serves SSH until ctx is done, and returns nil on a clean shutdown.
func (*Provider) ListenPort ¶
func (p *Provider) ListenPort(pc plugin.ProviderConfig) plugin.ListenPort
ListenPort implements plugin.PortProvider: where this listener would bind under pc, resolved without binding anything. It is the same value Listen resolves, so `tommy providers` and the running listener cannot disagree.
func (*Provider) RegisterIngress ¶
RegisterIngress implements plugin.Provider. Nothing is mounted: this provider speaks SFTP on a port of its own.