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

Note

There is a bug in VSCode 1.23.0 related to configurations. This results in configurations that get added/removed to/from the global settings not showing up/disappearing until reload.

Usage

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

{
  "sshfs.configs": [
    {
        // Unique id, which results in ssh://serverlogs/
        "name": "serverlogs",
        // The label to usually display (uses the name by default)
        "label": "Server logs"
        // 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, all entries get merged together in one array.

There's an extensive JSON schema, so it'll say when you're missing a field. Mind that when you have to use e.g. either "host" or "putty", VSCode will only say "Missing host". Check your intellisense/autocomplete for all possible options.

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
  • Seems like I might've fixed this bug over time, but difficult to say
• 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 DONE (not the best, but eh)
• Configuring a deleted (but active) configuration should show the old config DONE
• 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 DONE
  • 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