diff --git a/README.md b/README.md index f4e1d36..03a3078 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,94 @@ # SSH FS - ![Logo](./resources/Logo.png) -[![GitHub package version](./media/github.png)](https://github.com/SchoofsKelvin/vscode-sshfs) -[![Visual Studio Marketplace](https://vsmarketplacebadge.apphb.com/version-short/Kelvin.vscode-sshfs.svg)](https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs) - [![Donate](./media/paypal.png)](https://www.paypal.me/KSchoofs) +[![GitHub package version](https://img.shields.io/github/v/release/SchoofsKelvin/vscode-sshfs?include_prereleases&label=GitHub%20version)](https://github.com/SchoofsKelvin/vscode-sshfs) +[![Visual Studio Marketplace](https://img.shields.io/visual-studio-marketplace/v/Kelvin.vscode-sshfs?label=VS%20Marketplace&logo=sdf)](https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs) +[![OpenVSX Registry](https://img.shields.io/open-vsx/v/Kelvin/vscode-sshfs?label=Open%20VSX)](https://open-vsx.org/extension/Kelvin/vscode-sshfs) +[![VS Market installs](https://img.shields.io/visual-studio-marketplace/i/Kelvin.vscode-sshfs?color=green&label=Installs)](https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs) +[![GitHub Sponsors](https://img.shields.io/github/sponsors/SchoofsKelvin?color=green&label=GitHub%20Sponsors)](https://github.com/sponsors/SchoofsKelvin) +[![Donate](./media/paypal.png)](https://www.paypal.me/KSchoofs) -This extension makes use of the new FileSystemProvider, added in version 1.23.0 of Visual Studio Code. It allows "mounting" a remote folder over SSH as a local Workspace folder. +This extension allows mounting remote folders as local workspace folders, launch integrated remote terminals and run `ssh-shell` tasks. -## Summary -* Use a remote directory (over SSH) as workspace folder -* Instantly create one or multiple terminals on the same host -* A built-in UI to add, edit and remove configurations -* Use agents, including Pageant and OpenSSH on Windows -* Use private keys (any supported by ssh2-streams, including PuTTY's PPK) -* Get prompted for a password/passphrase (plain text password aren't required) -* Easily create configurations that reference a PuTTY session/configuration -* Create tasks that run commands on a remote host (remote version of "shell" task type) -* Have multiple SSH (and regular) workspace folders at once -* Make use of SOCKS 4/5 and HTTP proxies and connection hopping +## Features -## Usage -Use the command `SSH FS: Create a SSH FS configuration`, or open the Settings UI using the `SSH FS: Open settings and edit configurations` and click Add: +### Config editor +The built-in config editor makes it easy to create and edit configurations: +![Config editor](./media/config-editor.png) -![Create a new configuration](./media/screenshot-create-config.png) +The config editors stores this, by default, in your User Settings (`settings.json`) as: +```json +"sshfs.configs": [ + { + "name": "hetzner", + "putty": "Hetzner", + "label": "Hetzner", + "hop": "hetzner2", + "root": "/root" + } +], +``` +This config is configured to copy settings (e.g. username, host, ...) from my PuTTY session. Due to me having loaded my private key in Pageant (PuTTY's agent), this config allows me to create a connection without having to provide a password/passphrase. It also specifies that all file operations _(`ssh://hetzner/some/file.js`)_ are relative to the `/root` directory on the server. -In this UI, you can also edit/delete existing configurations: +Configurations are read from your global User Settings, the current workspace's settings, and any JSON files configured with `sshfs.configpaths`. Even when the workspace overrides this setting, the globally-configured paths will still be read. The workspace versions do have higher priority for merging or ignoring duplicates. -![Config Editor](./media/screenshot-config-editor.png) +### Terminals +Using a simple button or the command palette, a remote terminal can be started: +![Terminals](./media/terminals.png) -To connect, either rightclick the name in the Explorer tab, or use the command panel: +_Uses `$SHELL` by default to launch your default user shell. A config option exists to change this, e.g. `"ksh -"` or `"exec .special-profile; $SHELL"`_ -![Connect](./media/screenshot-connect.png) +If a connection is already opened for a configuration, there is no need to reauthenticate. As long as the configuration hasn't changed, existing connections (both for workspace folders and terminals) will be reused. -This will add a Workspace folder linked to a SSH (SFTP) session: +### Remote shell tasks +A new task type `ssh-shell` is added to run shell commands remotely: +![Remote shell tasks](./media/shell-tasks.png) -![Workspace folder added](./media/screenshot-explorer.png) +The task terminal opens a full PTY terminal on the server. -## Changelog 1.18.0 -Starting from version 1.18.0 of the extension, a few new features are added: +### Remote workspace folders +Using a simple button or the command palette, we can mount a remote workspace folder as a regular local workspace folder: +![Remote workspace folder](./media/workspace-folder.png) -### Terminals -The configurations for SSH file systems can now also be used to spawn terminals: +_Same configuration used as from the [Config editor](#Config%20editor) above._ -![Terminals](./media/terminals.png) +This works seamlessly with extensions using the `vscode.workspace.fs` API _(added in VS Code 1.37.0)_, although not all extensions switched over, especially ones making use of binary files. + +As can be seen, right-clicking a remote directory gives the option to instantly open a remote terminal in this directory. + +The extension supports any `ssh://` URI. I actually opened `ssh://hetzner/ng-ui` as my folder, which resolves to `/root/ng-ui` on my remote server. By default, the button/command opens `ssh://hetzner/` which would then mount `/root`, as that is what my `Root` config field is set to. You can set it to whatever, including `~/path`. + +### Miscellaneous +The extension comes with a bunch of other improvements/features. Internally the [ssh2](https://www.npmjs.com/package/ssh2) package is used. The raw config JSON objects _(as seen in [Config editor](#Config%20editor))_ is, apart from some special fields, a one-on-one mapping of the config options supported by this package. Power users can edit their `settings.json` to e.g. make use of the `algorithms.cipher` field to specify a list of ciphers to use. + +Some other features worth mentioning: + +#### Prompt host/username/password/... for every connection +![Prompt username](./media/prompt-username.png) -Opening a terminal automatically sets the working directory to the `root` directory, unless a directory was explicitly selected to open the terminal in: +Active connections are reused to minimize prompts. A connection gets closed if there's no terminal or file system using it for over 5 seconds. -![Explorer Terminal](./media/explorer-terminal.png) +#### Proxy settings +Several proxy types (SSH hopping, HTTP and SOCKS 4/5) are supported: -This replaces the built-in "Open terminal" context menu option that isn't provided for remote field systems. For non-ssh:// file systems, the original "Open terminal" menu item is still displayed, the remote version only affects ssh:// file systems. +![Proxy settings](./media/proxy-settings.png) -### New task type -This extension adds a new task type `ssh-shell` which can be used to run commands on a configured remote host: +`SSH Hop` refers to using another configuration to hop through, similar to OpenSSH's `ProxyJump`: -![Tasks](./media/tasks.png) +![Hop config field](./media/hop-config.png) -Currently only the `command` field is supported. The goal is to replicate part of the `shell` task structure, e.g. an `args` array, support for `${workspaceFolder}`, ... +#### SFTP Command/Sudo and Terminal command +![SFTP and Terminal Command config fields](./media/sftp-config.png) -### Connection reuse -The way the extension connects to the remote hosts is reworked. The extension tries to only keep one connection per host active, with one connection supporting the file system access and a bunch of terminals. If the saved configuration has changed after a connection has been established, the next terminal/filesystem will start a new connection, but leave the first one alive and fine. +The extension supports using a custom `sftp` subsystem command. By default, it uses the `sftp` subsystem as indicated by the remote SSH server. In reality, this usually results in `/usr/lib/openssh/sftp-server` being used. -A handy enhancement this brings is that prompts (e.g. for passwords) should only happen once. As long as a connection is open (either by having a connected file system or terminal to the host), opening e.g. a new terminal skips the whole authentication phase and is basically instant. +The `SFTP Command` setting allows specifying to use a certain command instead of the default subsystem. The `SFTP Sudo` setting makes the extension try to create a sudo shell _(for the given user, or whatever sudo defaults to)_ and run `SFTP Command` _(or `/usr/lib/openssh/sftp-server` by default)_. For most users, setting this to `` should allow operating on the remote file system as `root`. Power users with esoteric setups can resort to changing `SFTP Command` to e.g. `sudo /some-sftp-server`, but might run into trouble with password prompts. -Connections without an active file system or terminals will automatically be closed somewhere after 5 seconds. If you're planning on running a bunch of tasks on a host without having a workspace folder connected to it, keeping a terminal open is handy and advised. +The `Terminal command` option, as mentioned in [Terminals](#Terminals), allows overriding the command used to launch the remote shell. By default, the extension launches a remote shell over the SSH connection, runs `cd ...` if necessary, followed by `$SHELL` to start the user's default shell. This config option allows to replace this `$SHELL` with a custom way way of starting the shell, or configuring the provided default SSH shell. -### Logging -Logging has slightly improved, resulting in better logs that help with resolving issues. \ No newline at end of file +## Links +- [GitHub](https://github.com/SchoofsKelvin/vscode-sshfs) ([Issues](https://github.com/SchoofsKelvin/vscode-sshfs/issues) | [(Pre)-releases](https://github.com/SchoofsKelvin/vscode-sshfs/releases) | [Roadmap](https://github.com/SchoofsKelvin/vscode-sshfs/projects/1) | [Sponsor](https://github.com/sponsors/SchoofsKelvin)) +- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs) +- [Open VSX Registry](https://open-vsx.org/extension/Kelvin/vscode-sshfs) diff --git a/media/add-workspace-folder.png b/media/add-workspace-folder.png new file mode 100644 index 0000000..ce16bb5 Binary files /dev/null and b/media/add-workspace-folder.png differ diff --git a/media/config-editor.png b/media/config-editor.png new file mode 100644 index 0000000..de00d5a Binary files /dev/null and b/media/config-editor.png differ diff --git a/media/explorer-terminal.png b/media/explorer-terminal.png deleted file mode 100644 index bf443d2..0000000 Binary files a/media/explorer-terminal.png and /dev/null differ diff --git a/media/github.png b/media/github.png deleted file mode 100644 index 67125a2..0000000 Binary files a/media/github.png and /dev/null differ diff --git a/media/hop-config.png b/media/hop-config.png new file mode 100644 index 0000000..7224449 Binary files /dev/null and b/media/hop-config.png differ diff --git a/media/prompt-username.png b/media/prompt-username.png new file mode 100644 index 0000000..3e50adc Binary files /dev/null and b/media/prompt-username.png differ diff --git a/media/proxy-settings.png b/media/proxy-settings.png new file mode 100644 index 0000000..669db95 Binary files /dev/null and b/media/proxy-settings.png differ diff --git a/media/screenshot-commandpanel.png b/media/screenshot-commandpanel.png deleted file mode 100644 index a676684..0000000 Binary files a/media/screenshot-commandpanel.png and /dev/null differ diff --git a/media/screenshot-config-editor.png b/media/screenshot-config-editor.png deleted file mode 100644 index 889ca82..0000000 Binary files a/media/screenshot-config-editor.png and /dev/null differ diff --git a/media/screenshot-connect.png b/media/screenshot-connect.png deleted file mode 100644 index a979414..0000000 Binary files a/media/screenshot-connect.png and /dev/null differ diff --git a/media/screenshot-create-config.png b/media/screenshot-create-config.png deleted file mode 100644 index e86fd44..0000000 Binary files a/media/screenshot-create-config.png and /dev/null differ diff --git a/media/screenshot-explorer.png b/media/screenshot-explorer.png deleted file mode 100644 index 3cf9d45..0000000 Binary files a/media/screenshot-explorer.png and /dev/null differ diff --git a/media/sftp-config.png b/media/sftp-config.png new file mode 100644 index 0000000..34745a6 Binary files /dev/null and b/media/sftp-config.png differ diff --git a/media/shell-tasks.png b/media/shell-tasks.png new file mode 100644 index 0000000..e87c911 Binary files /dev/null and b/media/shell-tasks.png differ diff --git a/media/tasks.png b/media/tasks.png deleted file mode 100644 index d465905..0000000 Binary files a/media/tasks.png and /dev/null differ diff --git a/media/terminals.png b/media/terminals.png index d8a68f5..c661f5d 100644 Binary files a/media/terminals.png and b/media/terminals.png differ diff --git a/media/workspace-folder.png b/media/workspace-folder.png new file mode 100644 index 0000000..7ac859e Binary files /dev/null and b/media/workspace-folder.png differ diff --git a/package.json b/package.json index 6775ba2..184a85f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "vscode-sshfs", "displayName": "SSH FS", - "description": "File system provider using SSH", + "description": "File system, terminal and task provider using SSH", "publisher": "Kelvin", "version": "1.19.2", "engines": { @@ -28,6 +28,7 @@ "onCommand:sshfs.refresh" ], "main": "./dist/extension.js", + "homepage": "https://github.com/SchoofsKelvin/vscode-sshfs", "author": { "name": "Kelvin Schoofs", "email": "schoofs.kelvin@gmail.com", @@ -48,7 +49,31 @@ "sshfs", "sync", "filesystem", - "terminal" + "terminal", + "sftp", + "scp" + ], + "badges": [ + { + "url": "https://img.shields.io/github/v/release/SchoofsKelvin/vscode-sshfs?include_prereleases&label=GitHub%20version", + "href": "https://github.com/SchoofsKelvin/vscode-sshfs/releases", + "description": "Releases on GitHub" + }, + { + "url": "https://img.shields.io/open-vsx/v/Kelvin/vscode-sshfs?label=Open%20VSX", + "href": "https://open-vsx.org/extension/Kelvin/vscode-sshfs", + "description": "Open VSX Registry" + }, + { + "url": "https://img.shields.io/visual-studio-marketplace/v/Kelvin.vscode-sshfs?label=VS%20Marketplace&logo=sdf", + "href": "https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs", + "description": "Visual Studio Marketplace" + }, + { + "url": "https://img.shields.io/visual-studio-marketplace/i/Kelvin.vscode-sshfs?label=Installs", + "href": "https://marketplace.visualstudio.com/items?itemName=Kelvin.vscode-sshfs", + "description": "Unique installs using Visual Studio Marketplace" + } ], "contributes": { "views": {