sftp

Overview ¶

Package sftp - SFTP VFS implementation.

Usage ¶

Rely on github.com/c2fo/vfs/v7/backend

  import(
	  "github.com/c2fo/vfs/v7/backend"
	  "github.com/c2fo/vfs/v7/backend/sftp"
  )

  func UseFs() error {
	  fs := backend.Backend(sftp.Scheme)
	  ...
  }

Or call directly:

  import "github.com/c2fo/vfs/v7/backend/sftp"

  func DoSomething() {
	  fs := sftp.NewFileSystem()

	  location, err := fs.NewLocation("myuser@server.com:22", "/some/path/")
	  if err != nil {
		 #handle error
	  }
	  ...
  }

sftp can be augmented with some implementation-specific methods. Backend returns vfs.FileSystem interface so it would have to be cast as sftp.FileSystem to use them.

  func DoSomething() {
	  // cast if fs was created using backend.Backend().  Not necessary if created directly from sftp.NewFileSystem().
	  fs := backend.Backend(sftp.Scheme)
	  fs = fs.(*sftp.FileSystem)

	  // to pass specific client
	  sshClient, err := ssh.Dial("tcp", "myuser@server.com:22", &ssh.ClientConfig{
		  User:            "someuser",
		  Auth:            []ssh.AuthMethod{ssh.Password("mypassword")},
		  HostKeyCallback: ssh.InsecureIgnoreHostKey,
	  })
	  #handle error
	  client, err := _sftp.NewClient(sshClient)
	  #handle error

	  fs = sftp.NewFileSystem(sftp.WithClient(client))

	  // to pass in client options. See Options for more info.  Note that changes to Options will make nil any client.
	  // This behavior ensures that changes to settings will get applied to a newly created client.
	  fs = sftp.NewFileSystem(
		  WithOptions(
		      sftp.Options{
			      KeyFilePath:   "/home/Bob/.ssh/id_rsa",
			      KeyPassphrase: "s3cr3t",
			      KnownHostsCallback: ssh.InsecureIgnoreHostKey,
		      },
		  ),
	  )

	  location, err := fs.NewLocation("myuser@server.com:22", "/some/path/")
	  #handle error

	  file := location.NewFile("myfile.txt")
	  #handle error

	  _, err := file.Write([]bytes("some text")
	  #handle error

	  err := file.Close()
	  #handle error
  }

Authentication ¶

Authentication, by default, occurs automatically when Client() is called. Since user is part of the URI authority section, auth is handled slightly differently than other vfs backends.

A client is initialized lazily, meaning we only make a connection to the server at the last moment so we are free to modify options until then. The authenticated session is closed any time WithOption(), WithClient(), or Close() occurs. Currently, that means that closing a file belonging to an fs will break the connection of any other open file on the same fs.

USERNAME ¶

User may only be set in the URI authority section.

 scheme             host
 __/             ___/____  port
/  \            /        \ /\
sftp://someuser@server.com:22/path/to/file.txt
       \____________________/ \______________/
       \______/       \               \
           /     authority section    path
     username

sftp vfs backend accepts either a password or an ssh key, with or without a passphrase.

PASSWORD/PASSPHRASE

Passwords may be passed via Options.Password or via the environmental variable VFS_SFTP_PASSWORD.

SSH keys may be passed via Options.KeyFilePath and (optionally) Options.KeyPassphrase. They can also be passed via environmental variables VFS_SFTP_KEYFILE and VFS_SFTP_KEYFILE_PASSPHRASE, respectively.

KNOWN HOSTS ¶

Known hosts ensures that the server you're connecting to hasn't been somehow redirected to another server, collecting your info (man-in-the-middle attack). Handling for this can be accomplished via:

1. Options.KnownHostsString which accepts a string.
2. Options.KnownHostsFile or environmental variable VFS_SFTP_KNOWN_HOSTS_FILE which accepts a path to a known_hosts file.
3. Options.KnownHostsCallback which allows you to specify any of the ssh.AuthMethod functions. Environmental variable VFS_SFTP_INSECURE_KNOWN_HOSTS will set this callback function to ssh.InsecureIgnoreHostKey which may be helpful for testing but should not be used in production.
4. Defaults to trying to find and use <homedir>/.ssh/known_hosts. For unix, system-wide location /etc/ssh/.ssh/known hosts is also checked. SSH doesn't exist natively on Windows and each third-party implementation has a different location for known_hosts. Because of this, no attempt is made to find a system-wide file for Windows. It's better to specify in KnownHostsFile in that case.

OTHER OPTIONS ¶

Passing in multiple host key algorithms, key exchange algorithms is supported - these are specified as string slices. Example:

fs = sftp.NewFileSystem(
	sftp.WithOptions(
		sftp.Options{
			KeyExchanges: []string{ "diffie-hellman-group-a256", "ecdh-sha2-nistp256" },
			Ciphers: []string{ "aes256-ctr", "aes192-ctr", "aes128-ctr" },
			MACs: []string{ "hmac-sha2-256", "hmac-sha2-512" },
			HostKeyAlgorithms: []string{ "ssh-rsa", "ssh-ed25519" },
			ConnectTimeout: 15, // 15-second timeout for connection and auth
			// other settings
		},
	),
)

FilePermissions ¶

The `FilePermissions` option allows you to specify the file permissions for files created or modified using the SFTP backend. These permissions will override the sftp server or underlying filesystem's umask (default permissions). Permissions should be specified using an octal literal (e.g., `0777` for full read, write, and execute permissions for all users).

Example:

fs = sftp.NewFileSystem(
	sftp.WithOptions(
		sftp.Options{
 			FilePermissions: "0777", // Correctly specify permissions as octal (in string form)
			// other settings
		},
	),
)

When a file is opened for Write() or Touch()'d, the specified `FilePermissions` will be applied to the file.

AutoDisconnect ¶

When dialing a TCP connection, Go doesn't disconnect for you. This is true even when the connection falls out of scope, and even when garbage collection is forced. The connection must be explicitly closed. Unfortunately, VFS.FileSystem has no explicit close mechanism.

Instead, the SFTP backend will automatically disconnect 10 seconds (default) after connection. This disconnect timer is canceled anytime a server-side request (like list, read, etc) is made. Once the request has completed, a new timer will begin. If the timer expires (because it is not interrupted by any request), the server connection will be closed. Any subsequent server request will first reconnect, perform the request, and start a new disconnect timer.

Options.AutoDisconnect accepts an integer representing the number seconds before disconnecting after being idle. Default value is 10 seconds.

Any server request action using the same underlying FileSystem (and therefore sftp client), will reset the timer. This should be the most desirable behavior.

ConnectTimeout ¶

By default, the SFTP backend will wait indefinitely for a connection to be established and for the authentication handshake to complete. This can cause an application to hang if the remote server is unresponsive or misconfigured (e.g., it never responds after an incorrect password).

The `ConnectTimeout` option sets a deadline for the entire connection process, including TCP connection and SSH authentication. If the connection and authentication do not succeed within this duration, the operation will fail with a timeout error.

`Options.ConnectTimeout` accepts an integer representing the number of seconds. The default value is 30 seconds.

Example:

fs := sftp.NewFileSystem(
	sftp.WithOptions(
		sftp.Options{
			ConnectTimeout: 15, // Set a 15-second timeout for connection and auth
			// other settings
		},
	),
)

func doSFTPStuff() {
	fs := sftp.NewFileSystem()
	loc, err := fs.NewLocation("myuser@server.com:22", "/some/path/")
	file1, _ := loc.NewFile("file1.txt")
	file2, _ := loc.NewFile("file2.txt")
	file1.Touch()                               // "touches" file and starts disconnect timer (default: 10sec)
	_, _ := loc.List()                          // stops timer, does location listing, resets timer to 10 seconds
	file2.Touch()                               // stops timer, "touches" file2, resets timer to 10 seconds
	time.Sleep(time.Duration(15) * time.Second) // pause for 15 seconds, disconnects for server after 10 seconds
	_, _ := loc.List()                          // reconnects, does location listing, starts new disconnect timer
	return
}

func main {
	// call our sftp function
	doSFTPStuff()
	// even though the vfs sftp objects have fallen out of scope, our connection remains UNTIL the timer counts down

	// do more work (that take longer than 10 seconds)
	doOtherTimeConsumingStuff()

	// at some point during the above, the sftp connection will have closed
}

NOTE: AutoDisconnect has nothing to do with "keep alive". Here we're only concerned with releasing resources, not keeping the server from disconnecting us. If that is something you want, you'd have to implement yourself, injecting your own client using WithClient().