vscode-sshfs/README.md

SSH FS

This extension makes use of the new FileSystemProvider, added in version 1.23.0 of Visual Studio Code.

Features

• Use a remote directory (over SSH) as workspace folder
• Use agents, including Pageant for Windows
• Get prompted for a password/passphrase (no plain text password in settings)
• Easily create configurations that mirror a PuTTY session
• Have multiple SSH workspace folders at once

Usage

Add SSH FS configs to "sshfs.configs" in your User Settings:

{
  "sshfs.configs": [
    {
        // Both display name and what results in ssh://serverlogs/
        "name": "serverlogs",
        // Remote folder to use as root (default is /)
        "root": "/var/log",
        // Host to connect to (domain / IPv4 / IPv6)
        "host": "10.0.0.123",
        // Port to connect to (default is 22)
        "port": 22,
        // Username to login with
        "username": "root",


        // Path to ssh-agent's UNIX socket (cygwin ones should work too)
        // or 'pageant' when using Pageant on Windows
        "agent": "pageant",
        
        // Instead of using an agent, we can also just use a password
        "password": "CorrectHorseBatteryStaple",
        // We can also make the extension prompt us for it instead
        "password": true,
        

        // Or a private key (raw key, OpenSSH format)
        // (can also be a public key for host-based authentication)
        "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnN...",
        // Should the private key be encrypted
        "passphrase": "CorrectHorseBatteryStaple",
        // Same as with the password, we can let it prompt us
        "passphrase": true
    },
    {
        // If you're on Windows and have PuTTY installed
        "name": "media-server",
        "root": "/data/media/",


        // Either set this to a session name
        "putty": "My media server",

        // Or let it find one using the host (and username)
        "putty": true,
        // Can also be a session name, e.g. "My media server"
        "host": "my.media.me",
        // (Optional) Filter the session by username
        // (This only works if host is NOT a name of a session)
        "username": "media",


        // If the session has an encrypted key
        "passphrase": "CorrectHorseBatteryStaple"

        // Note: If the session doesn't specify a username, but
        // has "Use system username" enabled, it'll use process.env.USER

        // Note: The "agent" option will be set to "pageant" if the
        // session has "Attempt authentication using Pageant" set
    },
    {
        // With PuTTY, this can be a complete configuration (with / as root)
        "name": "quick-putty",
        "putty": "My PuTTY session"
    }
  ],
}

You could also put them in Workspace settings, it merges instead of overrides

The name has to be a certain format, creating a new configuration using the Command Pallet (or rightclicking the SSH File Systems view) is recommended. Think of the name as an internet domain name, and you'll be more than fine.

Either rightclick to Connect or use the command panel

This will add a Workspace folder linked to a SSH (SFTP) session:

TO DO (in order of most likely to implement first)

• Fix bug where saving a file resets the permissions (when owner/root at least) DONE
• Allow loading PuTTY sessions when on windows DONE
  • Also have a command to directly use a PuTTY session (TODO)
• Add proper JSON schema/validation for SSH FS configurations DONE
• Fix bug where the Explorer shows a loading bar forever
• Fix bug where VSCode shows an error message about no provider for ssh://NAME/
• Allow loading (or automatically use) sessions from .ssh/config
• An icon for the extension
• Configuring a deleted (but active) configuration should show the old config
  • Currently it'll open a new default configuration file for it
• Better error handling
  • Everything seems fine, but I haven't tested (a lot of) error situations
  • Handle wrong password/key/... properly DONE
    • Maybe prompt for a password when one's needed but not configured? (TODO)
  • Doesn't report when root is set to a non-existant directory
  • Doesn't (always?) report errors related to lacking permissions
• Offer reconnecting if the User Settings change
  • Currently this only refreshes the SSH File Systems view
  • We do offer this when it's changed using Configure in the context menu
• Icons for the SSH File Systems view
  • Icon for a configuration that isn't active
  • Icon for a configuration that's active and connected
  • Icon for a configuration that's active but disconnected
  • Variant for the above two for deleted configurations
• Better authentication methods
  • Currently (basically) everything is directly passed to ssh2
  • Add promptForPasswordOrPassphrase (self-explanatory) DONE
    • Both password and passphrase can be set to true to prompt
  • Add privateKeyPath (or auto-detect privateKey as a path)
  • Prompt the user for a password if the server prompts
    • This would be the tryKeyboard option for ssh2's Client.connect
    • Would need to hook into the keyboard request and show a prompt
• Add an option to open a SSH terminal (might as well)
• Add an option to change the root folder (without reconnecting)
  • Internally keep track of the original root folder (reset option)
  • Allow to "move" the root folder up one directory or to /
  • Add a context menu option for directories in the Explorer