Introduction

Welcome to SFTP Drive, a powerful solution for accessing remote resources as if they were local, eliminating the need to download and upload files you need to access and work with. Once installed, you can create a new drive, or mount point, by entering your server information and running the application in order to start browsing the file system.

Features:

  • Work with a remote file system as if it were on your local machine.
  • Support for Windows and Linux operating systems.
  • Support for multiple drive configurations.
  • Work with files via your favorite file manager.
  • Run as a Windows service or a desktop application.
  • Handles directory and file operations such as move, copy, and rename.
  • Supports password authentication.
  • Enables key-based and multi-factor authentication.
  • Support for PPK, PEM, PFX, File-based, and Windows stores.
  • Optional asynchronous-mode caching for a better experience while browsing files.
  • Work with any physical security key that supports PKCS11 (including YubiKey devices).

Additional Information

You will always find the latest information about SFTP Drive at our web site: www.nsoftware.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@nsoftware.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@nsoftware.com.

Thank You!

Thank you for choosing SFTP Drive. We realize that you have a choice among tools, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Running SFTP Drive

SFTP Drive supports running on Windows, Linux and macOS. On Windows the application can be configured from the main window. On Linux and macOS the application can be controlled using the command line.

Windows

The application can be started directly from the application's main window, via command line, or configured to run as a Windows service. Please take a look at the Quick Start Guide for a step-by-step introduction. Drives may be managed from the Drives tab (see Drive Management for more information).

Application

The buttons in the main application window or the context menu in the System Tray may be used to manage the application. To start the enabled drives, click the Start button. Once started, the options to Stop or Restart the application are enabled. Unmount all drives by clicking the Stop button.

All the configured drives will be displayed in list of drives. Click Save Changes to store changes across stopping and starting. For more information on configuring a drive please see the Drive Configuration topic.

Starting as a Windows Service

The application may also be configured to run as a Windows service. To enable running as a Windows service, navigate to the Service tab and check the Run as a Windows Service checkbox. Click Save Changes to save the changes.

After Save Changes is pressed, no user interaction is required to start the application. The Windows service will be configured with a startup type of automatic. The user interface does not need to remain open when running as a Windows service.

Command Line Parameters

The application may also be controlled via the command line. The command line values allow management of the application from unattended configurations such as scripts. The following command line parameters are available:

/stop Disconnects all drives and then exits the application
/start Starts the application and connects all enabled drives.
/start uimin Starts the application minimized and connects all enabled drives.
/servicestart Starts the SFTP Drive service
/servicestop Stops the SFTP Drive service
/isolated Launches SFTP Drive in Isolated Mode
/registerservice Registers the SFTP Drive service with Windows
/unregisterservice Unregisters the SFTP Drive service with Windows
/start /drive DRIVE_NAMEStarts the application and mounts the drive with the specified name. Multiple drives may be mounted by specifying multiple /drive flags. For instance: /start /drive mydrive1 /drive mydrive2
/stop /drive DRIVE_NAMEDisconnects the specified drive. Multiple drives may be disconnected by specifying multiple /drive flags. For instance: /stop /drive mydrive1 /drive mydrive2

Linux and macOS

Prerequisites

In order for the application to function properly, the following prerequisites must be met on the target machine.

  • .NET: The application requires that .NET 6 or higher is installed to the system. Please refer to the Microsoft documentation for instructions to install .NET on your version of Linux. In most cases, this can be achieved using the following commands.
    • For RedHat/CentOS derivative distributions: sudo yum install dotnet-runtime-6.0
    • For Debian/Ubuntu derivative distributions: sudo apt-get install dotnet-runtime-6.0
  • FUSE 2: The application requires that the system's kernel must have been compiled with support for FUSE 2. Additionally, the FUSE 2 libraries must be installed. Support for FUSE 3 is coming soon. In most cases, one of the following commands can be used:
    • For RedHat/CentOS derivative distributions: sudo yum install fuse-libs
    • For Debian/Ubuntu derivative distributions: sudo apt-get install libfuse2

Installing a License

To get started with SFTP Drive go ahead and install a license. Run the below command and specify a product key to install a full version license. Optionally run the command without a product key to install a free version license.

  dotnet sftpdrive.dll install-license [PRODUCT_KEY]

Start the Drive via Command Line

The command line arguments allow managing the application in unattended and interactive configurations. The application allows specifying all connection settings with the start command. Please see the Quick Start Guide for a step-by-step introduction.

dotnet sftpdrive.dll start user@remotehost[:/remote/path] /path/to/local/mount [-p 22] [-i id_rsa] [-v] [-q]

The following parameters are available with explicit drive creation.

-p --port The port of the remote host. The default value is 22 if this is not specified.
-i The absolute or relative path to an identity file to use when authenticating to the remote host.
-q --quiet Suppresses non-error messages.
-f Starts the process in the background. When specified, the process will continue to run in the background. The drive can be controlled using the 'status' and 'stop' commands.
-v Enables verbose logging. Specify '-vv' to enable debug logging.

Start the Drive via Configuration File

A configuration file may be used to specify connection settings and other advanced options. To start the drive with a configuration file, use the following command.

dotnet sftpdrive.dll start -c /path/to/config/file.conf

The following parameters are available with configuration files.

-c --config-file Specifies the absolute or relative path to a configuration file containing drive connection settings. See the included sftpdrive_example.conf file for details.
-q --quiet Suppresses non-error messages.
-f Starts the process in the background. When specified, the process will continue to run in the background. The drive can be controlled using the 'status' and 'stop' commands.
-v Enables verbose logging. Specify '-vv' to enable debug logging.

Stop the Drive

The application can be stopped using the following command.

dotnet sftpdrive.dll stop

Status of the Drive

The drive status can be queried using the following command.

dotnet sftpdrive.dll status

Drive Help

For information on the available commands and parameters, use the following command.

dotnet sftpdrive.dll help
Example Configuration Settings

Below is a copy of the sftpdrive_example.conf file that is also included with the application. This file provides details about possible settings.

# SFTP Drive Example Configuration
#
# This is the SFTP Drive configuration file. See the online 
# documentation for more information.
#
#   https://cdn.nsoftware.com/help/NDH/app/
# 
# The syntax used for specifying options in this file is 
# one setting per line in a NAME=VALUE pattern. Uncommented
# options will override the default value. 

[Global]
# Determines whether or not passwords will be masked in the log.
#MaskSensitive=True
#MaxLogLines=1000

# Determines the level of detail in the log output. Valid values range from 
# 0 (off) to 5 (debug):
# 0 Off - Nothing will be logged.
# 1 Error - Only errors will be logged. 
# 2 Warning - Additional warning information will be logged. 
# 3 Info - General information about the status of the connection will be logged. 
# 4 Verbose - logs additional information bout the connection and detailed protocol information.
# 5 Debug - Logs detailed debug information, including raw data.  
#LogMode=3
#LogToFile=True
#LogFile="/root/.nsoftware/sftpdrive/logs/app.log"

# The logs may be rotated after a specified number of days or 
# log file size. When a log is rotated the existing log file will 
# be renamed to include the last date for which the log applies. 
# Logs may also be deleted after a specified number of days.
#RotateLogDays=0
#RotateLogSize=0
#DeleteLogDays=0

# Defines the number of seconds to wait for the mount operation to complete. 
#MountTimeout=20

# Specifies the number of reconnection attempts when a disconnect 
# occurs. Use a value of -1 to reconnect indefinitely.
#ReconnectAttempts=4

# Specifies the number of seconds to wait before reconnecting.
#ReconnectInterval=5

# Defines the number of seconds to wait for a response to a request. If 
# no response from the server is received after Timeout seconds an error occurs.
#Timeout=60

# Enables compression to be used on the SSH connection if the server supports it.
#UseCompression=False

# Determines whether files that start with a dot or period (.) are 
# marked as hidden when returned in a directory listing.
#HideDotFiles=False

# Determines whether files that start with a dot or period (.) are 
# returned in a directory listing.
#ShowDotFiles=True

# Specifies a comma-separated list of folders that cannot be created on 
# the virtual drive so will not be returned in directory listings. 
#    NOTE: Use with caution. When the system asks us to create these folders
#    we will respond with SYSERR_CANNOT_MAKE. Applications that rely on these
#    operations may behave unexpectedly. Specify a folder relative to the 
#    root of the virtual drive, for example: "/DoNotCreate"
#IgnoredDirs=""

# Specifies a comma-separated list of files the drive should ignore requests for. 
# Requests for the specified files will not be made to the server.
#    NOTE: For each file in the list we will respond with FILE_DOES_NOT_EXIST. 
#IgnoredFiles="autorun.inf,bootmgr,bootnxt,hiberfil.sys,pagefile.sys,desktop.ini"

# Specifies whether the application will use caching for file metadata 
# and directory enumeration entries.
#UseMetadataCache=True

# Defines the proxy connection details. 
#ProxyHost=""
#ProxyPassword=""
#ProxyPort=0

# Determines the type of proxy. (0 - HTTP Tunnel, 1 - SOCKS4, 2 - SOCKS5)
#ProxyType=2
#ProxyUsername=""

[AppInfo]
Name="SFTPDrive"

# The Drives section contains options for each drive. Multiple 
# drives may be specified, please scroll down for more details. 
[Drives/ExampleDrive]

Host="example.hostname.com"
#Port=22

Username="root"

# Determines whether the drive will be connected. This is True by default.
#Enabled=True

# Defines the location on the server filesystem that will correspond 
# to the root folder of the drive.
#RemoteRoot="/"

# Defines the location on the local disk where the drive will be 
# mounted. Note the folder must exist and be empty.
MountPoint="/path/to/mount/point"

# Determines the authentication method that will be used to connect to the server. 
#    0 - Password
#    1 - Public key
#    2 - Keyboard-interactive
#AuthType=0

# Optionally specify the password to be used. If not set the application will prompt
# for the password at runtime.
#Password=""

# When using certificate-based authentication, set the following CertStore* settings. 
#CertStore="/root/temp/test.ppk"
#CertStorePassword="test"

# Defines the file permissions for any new files created on the drive. After the file 
# has been created SFTP Drive will set the file's attributes. (Base 8 Digits)
#DefaultFilePermissions=664

# Defines the folder permissions for any new folders created on the drive. After the 
# folder has been created SFTP Drive will set the folder's attributes. (Base 8 Digits)
#DefaultFolderPermissions=775

# Determines whether or not to forcefully rename a file if the destination file 
# already exists. By default renaming a file will fail if the destination file exists.
#ForceRename=0

# Whether to query the server for available space when connecting.
#QueryAvailableSpace=True

# Defines allowable encryption algorithms in order of preference.
#SSHEncryptionAlgorithms="aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,arcfour256,arcfour128,arcfour,cast128-cbc,aes256-gcm@openssh.com,aes128-gcm@openssh.com,chacha20-poly1305@openssh.com"

# Defines allowable message authentication algorithms in order of preference.
#SSHMacAlgorithms="hmac-sha2-256,hmac-sha2-512,hmac-sha1,hmac-md5,hmac-ripemd160,hmac-sha1-96,hmac-md5-96,hmac-sha2-256-96,hmac-sha2-512-96,hmac-ripemd160-96,hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com"

# Defines allowable key exchange algorithms in order of preference. 
#SSHKeyExchangeAlgorithms="curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group14-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha256,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,ecdh-sha2-nistp256,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,ecdh-sha2-nistp384,ecdh-sha2-nistp521"

# Defines allowable signature algorithms in order of preference. Note this 
# is only applicable when using public key authentication.
#SSHPubKeyAuthSigAlgorithms="ssh-rsa,rsa-sha2-256,rsa-sha2-512,ssh-dss,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-ed25519"

# Specifies the time in seconds for which the directory information will
# be considered valid. This will improve performance by decreasing enumeration requests.
#    NOTE: Specifying a value of 0 means that directory information will not be 
#    cached and will result in a separate request to the SFTP server. 
#CacheInfoValidityTime=30

# Specifies the number of allowed concurrent operations.
#CacheConcurrentDownloadFilesMax=4
#CacheConcurrentUploadFilesMax=4

# Specifies the number of allowed connections per file.
#CacheConcurrentDownloadThreadsPerFile=4
#CacheConcurrentUploadThreadsPerFile=4

# Specifies whether partial file content will be stored locally and uploaded 
# at a later time. This will have a transmission speed improvement. The cache is enabled by default. 
#CacheEnable=False

# Specifies the location on disk where bits and pieces of files will be stored 
# and uploaded at a later time. 
#   NOTE: By default, the cache is stored in $HOME/.nsoftware/sftpdrive/cache/hostname.
#   If a drive name is supplied, the cache directory will be $HOME/.nsoftware/sftpdrive/cache/drivename.
#CacheDirectory=""

# Specifies whether file content should be cached locally when an application reads
# content from the virtual drive. This is only applicable if caching is enabled. 
#    NOTE: If the remote files are large this could significantly increase the
#    amount of disk space used by the cache. 
#CacheEnabledForRead=False

# Specifies the number of seconds to wait before removing the file from the cache. After
# the time has elapsed the file will be considered unused. 
#CacheFileDeleteDelay=5

# Specifies the number of seconds to wait before uploading the file. After the time has 
# elapsed the file will be uploaded to the server. This only applies to large files.
#CacheFileUploadDelay=5

# Specifies the maximum size in bytes of a file that will be uploaded immediately 
# without waiting for the upload delay. This is only applicable when caching is enabled.
#    NOTE: Specifying a value of 0 means the upload delay will apply to all files. 
#CacheFileUploadDelayThreshold=1048576

# Specifies the maximum number of retries for the upload operation. This is only
# applicable when caching is enabled. 
#CacheMaxUploadRetries=3

# Specifies the number of small files to pre-download. Files that are small enough
# will be pre-downloaded alphabetically. 
#    NOTE: Specifying a value of 0 means files will not be pre-downloaded. 
#CachePreDownloadSmallFileCount=4

# Specifies the size in bytes of a file that will be considered for pre-download. This is only
# applicable when pre-downloading files is enabled. 
#CachePreDownloadSmallFileSizeLimit=1048576

# Determines how often a keep-alive packet is sent to the server, in seconds. Specifying
# a value of 0 means no keep-alive packets will be sent. 
#SSHKeepAliveInterval=-1

# Determines the maximum number of keep-alive packets sent to the server. 
#SSHKeepAliveCountMax=-1

# This is the end of the Drives/ExampleDrive options. You may specify additional 
# drives and their corresponding options by adding additional [Drives/DriveName] groups below.

# The TrustedSSHHostKeys section is managed automatically and the application 
# will add trusted host keys after a user accepts a host key prompt during initial login.
[TrustedSSHHostKeys]

# Trusted host key entries store a SHA-256 fingerprint of the server's public key. Additional 
# entries may be added using the syntax hostname:port="SHA-256 Fingerprint"
# 
# When connecting to a host for the first time the application will prompt the user
# to accept the server's host key, and if accepted this section will automatically
# be updated.

#example.hostname.com:22="2c:a7:d8:7e:76:20:8d:06:07:72:d7:b2:22:91:8a:24:cc:ec:b6:f1:1c:59:2a:b7:de:16:34:b9:46:ad:69:48"

Drive Management

The Start and Stop buttons provide the basic functionality of SFTP Drive. Enabled drives are mounted when Start is pressed and all drives are unmounted when Stop is pressed. Start and Stop buttons can also be found in the system tray. The Restart button unmounts and subsequently mounts the currently running drives.

Press the Exit button to unmount any connected drives and stop the application. When running as a Windows Service, the Exit button will exit the graphical application and leave the service running. The service can be stopped from the application interface by clicking the Stop button or stopped manually in the Windows Service Manager.

The Drives tab is the control center for the application. Once a drive is configured it is added to the drive list. Select a drive from the drive list and click the control buttons on the right panel to change it or open it. Alternatively, right-click a particular drive and manage it from the context menu.

Working with Drives

  • The Edit... button opens the Drive Configuration window.
  • The Duplicate... button creates a new drive using the settings of the selected drive.
  • The Delete button permanently removes the drive from the drive list.
  • The Enable button designates a drive to be mounted when the Start button is pressed or the service is started.
  • The Disable button disables the drive so it cannot be mounted.
  • The Open button opens the remote folder associated with the selected drive.
  • The Connect button mounts the selected drive without affecting other drives.
  • The Disconnect button unmounts the selected drive without affecting other drives.

Configuration details about each drive are included in drive list. Click on the column headers to sort the drives by the respective category.

Drive Configuration

The drive configuration window is used to configure new drives and edit existing drives. It can be accessed by clicking the New... button in the Drives tab or clicking the Edit... button when a drive is selected in the drive list. Drive-specific configuration for example, the connection settings, the drive name, the drive selection settings, and the startup behavior are specified in this window (additional configuration can be specified in the Advanced tab).

Please be aware that configuration changes will not take effect until you click the Save Changes button in the SFTP Drive toolbar, which will save the settings to the Windows registry.

Adding a Drive

  • To add a drive, click the New... button on the Drives tab of the main window.
  • Enter a name for the drive in the Drive Name field, and if needed, choose the desired drive letter. This will be the drive letter where the remote file system will be mounted.
  • Enter your server's address and port in the Remote Host and Remote Port fields.
  • Enter your username in the Username: field.
  • Use the Authentication Type drop-down menu to choose the type of authentication and provide the corresponding credentials (see Authentication for more information).
  • The Remote Folder section provides additional options to use when connecting to the remote file system.

    • Root Folder on Server specifies which folder on the SFTP server should be treated as the root of the local drive when mounted.
    • Read-Only mode tells the application whether to mount the drive in read-only mode.
    • Open Remote Folder On Connect specifies which folder to open in Explorer when the drive is mounted (if any). If set, each time the drive is connected an Explorer window will open at the specified path. Uncheck this box to disable this functionality.

  • The Test SSH Connection button will verify the connection to the SFTP server can be successfully established. When configuration is complete press OK to complete the drive configuration.

After clicking OK the drive will be added to the drive list . Use the Advanced Settings to set additional configuration settings at the drive level and at the global level.

Authentication

Select the SSH authentication protocol by choosing an option from the Authentication Type dropdown in the Drive Configuration window. This setting can also be managed in the registry (see the AuthType value in the Advanced Settings for more information). When a particular method is selected the corresponding credentials can be specified in the configuration window.

Once you have entered your credentials click Test SSH Connection and if authentication is successful, the Host Key Fingerprint field will be populated with a SHA-256 fingerprint of the server's public key.

Supported Authentication Methods

  • Password
  • Public Key
  • Keyboard-Interactive
  • Multi-factor
  • Public Key (Pageant)
  • Public Key (Security key)
  • Password + OTP

Password Authentication

Selecting this authentication method instructs SFTP Drive to attempt to authenticate to the server using a username and password combination. If authentication fails, SFTP Drive will automatically fall back to Keyboard-Interactive mode.

Public Key Authentication

Selecting this option instructs SFTP Drive to attempt to authenticate to the server via the standard public key authentication mechanism supported by the SSH protocol. The user must set the location and format of the private key as well as a username to be able to authenticate.

Keyboard-Interactive Authentication

Selecting this authentication method instructs SFTP Drive to authenticate in a challenge-response cycle, displaying a response dialog for each prompt. Password prompts are automatically processed using the value entered in the password field in the Edit Drive dialog.

Multi-factor Authentication

Multi-factor authentication enables multiple forms of authentication. Typically servers will require a combination of password and public key authentication. Additional factors of authentication are also supported by specifying the appropriate credentials.

Public Key (Pageant)

Selecting this authentication method instructs SFTP Drive to communicate with PuTTY's ssh-agent "Pageant" over shared memory and perform public key authentication.

Note: Ensure SFTP Drive and Pageant are running with the same level of permission use this method of authentication.

Public Key (Security Key)

Selecting this authentication method instructs SFTP Drive to interact with a physical security key which will be used to authenticate to the server via the standard public key authentication mechanism. The user must load the PKCS #11 library that will allow SFTP Drive to interact with the security key.

Password + OTP

This authentication method combines a stored password with a One Time Password (OTP). When connecting the drive the application will prompt for the OTP and append this to the stored value when authentication to the server. The server must be configured to accept the password + OTP value as the user's password.

Advanced

The Advanced tab of the drive settings dialog provides access additional settings which are not commonly used.

Allow all users access to the drive

This option controls whether drives are visible to other users on the system. When checked (default), drives are accessible by all users on the system. When unchecked, the drive is only accessible by the account under which SFTP Drive is running.

Note: this setting should not be disabled when running as a Windows Service. When running as a Windows Service with sharing disabled only the identity of the Windows Service itself will be able to access the drive (typically the Network Service identity). For more information see Shared Drives.

Handle case-sensitive filenames

This option controls whether SFTP Drive should treat file requests as case-sensitive (treating uppercase and lowercase letters as being different). This is only applicable if your server's filesystem is case-sensitive.

To use this setting you must disable case-insensitivity in Windows by creating a value in the registry called HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive (DWORD) with a value of 0. Most Windows applications are not prepared to handle filenames in a case-sensitive manner so using case-insensitive apps may result in unexpected behavior.

This setting should only be enabled if there is a specific reason to do so.

Force rename if the target file already exists

This setting determines whether or not to forcefully rename a file if the destination file already exists. By default, renaming a file will fail if the destination file already exists.

If enabled and the destination file already exists, the destination file will be renamed to have a temporary extension as a backup. The original file will be renamed to the destination file and the temporary file will be deleted. If the rename operation fails for any reason the temporary file is renamed back to the destination file so effectively no changes occur when the rename fails.

Permissions Settings

This setting controls the unix permissions value for creation of files and folders on the remote system. If the remote host is not a unix machine or does not allow specifying file permissions explicitly, then changing this setting will have no effect.

All operations performed against the virtual drive will be performed against the remote host using the SFTP user credentials provided in Drive Configuration. Note that changing the permissions values influences who may access the file on the remote machine. This is also configurable via the DefaultFilePermissions and DefaultFolderPermissions settings in the registry under Drives.

Proxy Settings

If a proxy is required for connecting to the SFTP server, you can provide drive-specific proxy settings here. The application supports the following types of proxies:

  • HTTP Tunnel (most common)
  • SOCKS4
  • SOCKS5

Specify the Proxy Type, Address, Port, and, if applicable, the Username and Password. These settings are unique to each drive and will only be used when establishing a connection with that specific drive. If these settings are defined, they will override the global proxy settings (see Settings) for that individual drive. If these settings are not specified, the global proxy settings will be utilized during the connection.

You can optionally enable the Password Prompt checkbox, which will prompt the user for the drive-level proxy password each time the associated drive attempts a connection. In this case, Proxy Password will not be utilized.

Import and Export

Settings may optionally be imported and exported to facilitate migration between systems.

Exporting Settings

To export settings navigate to the Settings tab and click the Export link. Specify the location and filename where settings will be saved. By default the settings will be stored in INI file format.

Importing Settings

To import settings from an existing file navigate to the Settings tab and click Import link. Specify the filename of the .ini file to load.

Note about Sensitive Data

Sensitive fields such as passwords will be decrypted as part of the export process and stored in plaintext in the .ini file.

Additional Configuration

The Settings tab defines application-wide settings. Settings such as log settings, reconnection logic, etc. are controlled here.

Advanced settings are available through the Windows Registry which allow setting infrequently used values.

Settings

The Settings tab is used to configure application-wide settings. Please note that configuration changes will not take effect until you click the Save Changes button in the SFTP Drive toolbar. Options specific to Drives are configured via the Drives tab.

Logging Options

These options can be used to configure the application's logging features.

  • Write Log to a File checkbox defines whether logs are written to a file. By default logs are not written to a file and are only available in the Service tab.
  • Log Mode defines the verbosity of the logs generated by the application. The following Log Mode values are supported:
    • Off - Nothing will be logged.
    • Error - Only errors will be logged.
    • Warning - Additional warning information will be logged.
    • Info - General information about the status of the connection will be logged.
    • Verbose - Logs additional information about the connection and detailed protocol information.
    • Debug - Logs detailed debug information, including raw data.
  • Log Rotation is available when logging to a file. The logs may be rotated after a specified number of days, and the application can also be configured to automatically delete log files older than a specified number of days. When a log is rotated the existing log file will be renamed to include the last date for which the log applies. For instance myfile.log may be renamed to myfile-2020-07-15.log. The date portion of the rotated log name is in the format yyyy-MM-dd.

Connection Settings

The settings in this section allow granular control over the connection management. In most cases the settings specified here should not be adjusted. The default settings enable automatic reconnection in the case where the connection is dropped.

  • Automatically Reconnect specifies whether the application will attempt to automatically reconnect to the SFTP server if the connection is lost. When enabled, the application will attempt to reconnect indefinitely every 5 seconds by default.
  • Keep-alive Interval specifies the interval in seconds between keep-alive packets. Keep-alive packets are sent during periods of inactivity to maintain the connection with the server.
  • Timeout defines the number of seconds to wait for a response when a request is made. If no response from the server is received after Timeout seconds an error occurs.

For more advanced connection settings, please see Advanced Settings.

Proxy Settings

If a proxy is required to be used when connecting to the SFTP server, the proxy connection details may be specified here. The application supports the following types of proxies:

  • HTTP Tunnel (most common)
  • SOCKS4
  • SOCKS5

Specify the Proxy Type, Address, Port, and, if applicable, the Username and Password. Note that these are global proxy settings and will be used when establishing a connection for each drive. However, you may customize the proxy settings for specific drives to override the global settings within the Advanced tab.

Caching Information

All our drive products use various types of caching. Caching is a complex topic and the actual observed behavior can vary. Depending on the specifics of a situation, multiple different actors may be involved.

SFTP Drive caching is optional and enabled by default. Caching refers to application-agnostic logic that holds pieces of files on disk and uploads them later. It might be beneficial in certain situations to decrease the number of round trips, improve transmission speed, or improve responsiveness of the virtual disk. The default behavior of SFTP Drive is to translate I/o requests from the operating system directly into SFTP protocol messages representing file system operations.

Cache Overview

The cache is a storage location for file content and metadata. When applications interact with files on the virtual drive, they might behave differently. The cache mediates access to allow complete files to be uploaded regardless of how they were written. It also helps reduce the overhead of transmitting all operations received from the OS.

SFTP Drive will store cache files in the location specified by the Cache Directory setting in the advanced tab of the drive configuration page. The default location is %ProgramData%\SFTPDrive\<drive>.

File Read

When an application reads a file on the drive, we will start multiple download threads to download the requested byte range and subsequent chunks. If the file is small then the first thread will download the entire content. Once the file is closed, it is removed from the cache.

The CacheEnabledForRead setting in the registry controls whether the requested content from read operations will be stored in the SFTP Drive file cache. The CacheConcurrentDownloadThreadsPerFile config defines how many concurrent download threads can be active at the same time (one thread per chunk).

If the size of the file being read is smaller than CachePreDownloadSmallFileSizeLimit, we will pre-download other small files in alphabetical order in the background. The maximum size for files that will be pre-downloaded is controlled by the CachePreDownloadSmallFileSizeLimit setting. The maximum count of small files that will be pre-downloaded is controlled by the CacheConcurrentDownloadFileCount setting.

File Write

Once the file system driver receives a request to write a file, a corresponding cache file is created with the same size as the original. The modified byte ranges are noted in the cache metadata.

If an application writes to a file on the drive and the file is smaller than CacheFileUploadDelayThreshold and the entire file content is modified, then the file will be uploaded as soon as the file is closed. If only a piece is modified, then after the file is closed the entire content will be downloaded and the modifications applied to it. Then the entire file will be uploaded.

If an application writes to a file on the drive and file is larger than the CacheFileUploadDelayThreshold, then the cache will first ensure the chunks of the file are ready to be uploaded. Any chunks of the file which are partially modified will be first downloaded then modifications are applied to them. All modified chunks are uploaded after the file has been closed and CacheFileUploadDelay seconds have passed without any additional operations on the file.

File Information

The OS will ask for file information frequently. When CacheEnabledForRead is turned on, SFTP Drive will store file metadata such as size, creation time, and last modified time for a short time specified by the "Directory (Metadata) caching" setting which corresponds with the CacheInfoValidityTime configuration setting in the registry. If the OS sends subsequent requests for file information during this validity interval, the request will be serviced from the cache without provoking another round trip.

Separate from application-level caching, the filesystem driver will cache file information and service requests from the OS to improve the responsiveness of the virtual drive. This is controlled by the UseMetadataCache configuration setting.

Directory Information

Regardless of the "Enable Caching" checkbox, SFTP Drive will store the results of previous directory listing requests for a short time specified by the "Directory (Metadata) caching" setting which corresponds with the CacheInfoValidityTime configuration setting in the registry. If the OS sends subsequent requests during this validity interval, the request will be serviced from the cache without provoking another round trip.

Advanced Settings

Advanced options for SFTP Drive are stored in the Windows registry in HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22. This registry key holds settings that are available for SFTP Drive globally. Sub-keys at this path hold settings for individual drives, and trusted SSH host keys.

The following keys hold configuration information:

Registry KeyApplicable Settings
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22Global settings for the application.
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22\DrivesDrives hold drive specific settings.
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22\TrustedSSHHostKeysTrusted SSH Host Keys stores trusted host keys.

The following values can be configured within the root HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22 registry key:

NameTypeDescription
DeleteLogDaysDWORDSpecifies the number of days that log files will remain before being deleted. Only applies if RotateLogDays is greater than 0. If set to 0, old logs will not be deleted.
ForceFileCloseDWORD

Specifies whether to force the closure and subsequent update of the encrypted file on disk after the last handle to the file is closed. In general the application will update the header of the encrypted file on disk when the file is closed.

In some cases the system may not close the file immediately after the last handle is closed which results in the file on disk not being updated in a timely manner. This setting forces the closure of the file after the last handle is released. Possible values are:

  • 0 - Not Enabled
  • 1 - Enabled (default)
LogFileStringContains the path to the log file.
LogModeDWORDDetermines the level of logging:
  • 0 - Off. Nothing will be logged.
  • 1 - Error. Only errors in SFTP Drive's operation will be logged.
  • 2 - Warning. Additional warning information will be logged.
  • 3 - Info. General information about the status of the connection will be logged.
  • 4 - Verbose. Logs additional information about the connection and detailed protocol information.
  • 5 - Debug. Logs detailed debug information.
  • 6 - Debug2. Additional debug information. CAUTION: This generates a very large amount of data.
LogPortDWORDThe SysLog port that will be used to communicate between the service and the UI when SFTP Drive is running as a service.
LogToFileDWORDDetermines whether or not the log will be written to a file. The file itself is specified by LogFile.
  • 0 - The log will only be written to the Log window on the Service tab. (default)
  • 1 - The log will also be saved to a file.
MaskSensitiveDWORDDetermines whether or not passwords will be masked in the log.
  • 0 - Passwords will be visible in the log.
  • 1 - Passwords will be replaced with '*' characters in the log. (default)
MaxLogLinesDWORDDetermines the maximum number of lines that will be stored in the Log window in the Service tab.
MountTimeoutDWORDDetermines how long (in seconds) SFTP Drive will wait for Windows to mount a drive without reporting an error. The default is 20 seconds when this value is not present in the registry.
PasswordEncryptionMethodStringDetermines how passwords are encrypted for storage. The default value is Auto. Possible values are:
  • Auto (default) - Microsoft DPAPI is used to encrypt passwords. When running the application as a user (not as a Windows service) the passwords are encrypted and can only be decrypted by the current user.

    When running as a Windows service the passwords are encrypted for the machine and can be decrypted by any user on the machine. When running as a Windows service the user application and the service run under different accounts and must both be able to decrypt the values stored in the registry.

Additional values are reserved for future use.
PromptForRegPermissionsDWORDDetermines if SFTP Drive will ask for registry permissions if it does not have them when it tries to write to the registry.
  • 0 - SFTP Drive will not ask for registry permissions, instead bringing up a UAC dialog for one-time access.
  • 1 - SFTP Drive will ask to be granted registry permissions. If granted, UAC access will not be required in the future. (default)
RotateLogDaysDWORDSpecifies how many days SFTP Drive will use a log file before rotating to a new log file. If set to 0, the log file will never rotate.
RunAsServiceDWORDDetermines whether or not SFTP Drive will run as a service.
ShowDotFilesDWORDDetermines whether files that start with a dot or period (.) are returned in a directory listing.
  • 0 - Dot files are not returned, so they are not displayed in explorer.
  • 1 - Dot files are returned in the directory listing (default).
HideDotFilesDWORDDetermines whether files that start with a dot or period (.) are marked as hidden when returned in a directory listing.
  • 0 - Do not hide dot files (default).
  • 1 - Any dot files will be marked with the hidden attribute.
IgnoredDirsStringSpecifies a comma-separated list of folders should be ignored by the virtual drive. Each folder included on the list cannot be created on the virtual drive and will not be returned in directory listings. Please specify the folder relative to the root of the drive.

Note: Use with caution. When the system asks us to create these folders we will respond with SYSERR_CANNOT_MAKE. Applications or system components that rely on these filesystem operations may start to behave unexpectedly.

  • "" - Nothing is ignored (default).
  • "\$RECYCLE.BIN" - Prevents the system from creating a recycle bin folder.

IgnoredFilesString

Specifies a comma-separated list of files to ignore requests for. Windows may make frequent, informational requests for files that it needs such as desktop.ini. If the request being made by the operating system is for one of the files in this list, the request will not be made to the S3 provider.

For each file on this list, we will service the system's request without performing the operation against remote storage. We respond by telling the system the file does not exist for simplicity.

  • "autorun.inf,bootmgr,bootnxt,hiberfil.sys,pagefile.sys,desktop.ini,thumbs.db" (default).

UseMetadataCacheDWORDSpecifies whether SFTP Drive will use caching for file metadata and directory enumeration entries. Disabling will cause SFTP Drive to re-download this information when it is requested by Windows and will slow performance.
  • 0 - No cache
  • 1 - Use caching (default)
UseFIPSCompliantAPIDWORD

When this setting is enabled only FIPS approved algorithms will be used, and the system's implementations will be used. No internal implementations of cryptographic algorithms will be used. Possible values are:

  • 0 - Disabled (default)
  • 1 - Enabled

LogPacketsDWORDDetermines whether or not the contents of SFTP Packets will be written to the log. Note that the additional output from this mode will slow operation considerably, so it is recommended that it only be enabled when necessary to diagnose an issue.
  • 0 - SFTP packet contents will not be logged (default)
  • 1 - SFTP packet contents will be written to the log.
UseCompressionDWORDDetermines whether or not the SSH connection will use zlib compression.
  • 0 - No compression (default)
  • 1 - Use zlib compression
KeepAliveIntervalDWORDDetermines how often a keep alive packet is sent to the server, in seconds. If set to 0, no keep alive packets will be sent. The default value is 15.
LocalHostStringSpecifies the local IP address of the network interface to use when connecting. This settings is typically only useful in machines with multiple network interfaces.
ProxyCheckedDWORDSpecifies whether or not the proxy settings are enabled.
ProxyHostStringSpecifies the host that SFTP Drive will use to connect to the proxy.
ProxyPasswordStringSpecifies the password that SFTP Drive will use to connect to the proxy.
ProxyPortDWORDSpecifies the port that SFTP Drive will use to connect to the proxy.
ProxyTypeDWORDSpecifies the type of proxy that SFTP Drive will connect to.
  • 0 - None (default)
  • 1 - Tunnel
  • 2 - SOCKS4
  • 3 - SOCKS5
ProxyUsernameStringSpecifies the username that SFTP Drive will use to connect to the proxy.
ReconnectAttemptsDWORDSpecifies the number of times SFTP Drive will attempt to reconnect if the connection to the server is lost.
ReconnectIntervalDWORDSpecifies the time (in seconds) between attempting another reconnection to the server. Default is 5 seconds.
TimeoutDWORDDetermines how many seconds SFTP Drive will wait for a response from the server before ending the connection.

Drives

The following values can be configured independently for each drive, at HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22\Drives\{Drive Name}:

NameTypeDescription
DriveLetterStringContains the drive letter where the drive will be mounted (e.g. "Z:").
DriveNameStringContains the name that will be displayed for the drive.
DriveTypeDWORDDetermines the type of drive that will be mounted:
  • 0 - Network Drive (default)
  • 1 - Local Disk
  • 2 - Removable Disk
EnabledDWORDDetermines whether or not the drive will be mounted when SFTP Drive is started.
  • 0 - Disabled
  • 1 - Enabled
IndexDWORDThe position of the drive in the list of drives.
OpenRemoteFolderDWORDDetermines whether or not SFTP Drive will automatically open a folder after mounting the drive.
  • 0 - Disabled
  • 1 - Enabled
OpenSpecifiedFolderStringContains the folder that SFTP Drive will open if OpenRemoteFolder is enabled.
ProxyHostStringSpecifies the host that SFTP Drive will use to connect to the proxy.
ProxyPasswordStringSpecifies the password that SFTP Drive will use to connect to the proxy.
ProxyPortDWORDSpecifies the port that SFTP Drive will use to connect to the proxy.
ProxyTypeDWORDSpecifies the type of proxy that SFTP Drive will connect to.
  • 0 - None (default)
  • 1 - Tunnel
  • 2 - SOCKS4
  • 3 - SOCKS5
ProxyUsernameStringSpecifies the username that SFTP Drive will use to connect to the proxy.
PromptForProxyPasswordDWORDWhen this setting is enabled, the application will prompt the user for the drive-level proxy password, which will be used to connect to the proxy specified with the drive-level proxy settings.
  • 0 - Disabled (default)
  • 1 - Enabled
ReadOnlyDWORDDetermines whether or not SFTP Drive will mount the drive in read-only mode.
  • 0 - Disabled (default)
  • 1 - Enabled
RemoteRootStringContains the folder on the server that SFTP Drive will use as the root of the mounted drive.
SharedDWORDDetermines whether or not other users can access the mounted drive.
  • 0 - Private
  • 1 - Shared (default)
CaseSensitiveNamesDWORDEnabling this setting will turn on case-sensitive mode in the virtual drive. The drive will advertise to Windows that it is sensitive to filename casing. This will allow some applications to work with files on the drive in a case-sensitive manner. Please keep reading for more information.

Windows treats file and directory names as case-insensitive. FOO.txt and foo.txt are treated as equivalent files. Although there are mechanisms to configure case-sensitivity in Windows, some applications may still make the assumption that the file system is case-insensitive. It is not uncommon for applications to transform filenames to use all upper or lower case. Please see the Microsoft Documentation for more information.

It is required for user-mode code of Windows to set the obcasesensitive setting to 0, in order to perform operations in a case-sensitive manner. Despite this setting, applications may assume the file system is case-insensitive. There is not a magic bullet to turn everything into case-sensitive. Applications may stop working in unexpected places.

By default, the virtual drive will advertise to Windows that is case preserving while it remains mounted. If the drive is started and then stopped and started again, you may see the case preserving is not persistent. For performance reasons we do not perform extra search operations to ensure the persistence of case preserving across stopping and starting the drive.

  • 0 - Disabled (default)
  • 1 - Enable case-sensitive mode

SftpServerExecStringA command to start the SFTP server. When this setting is specified, SFTP Drive opens an exec channel and sends the command to start the SFTP server over the channel. The subsequent SFTP requests and data are also sent over the command channel.

Note the server must be configured with passwordless sudo for the current SSH user. The default value is empty and channels are started using an SFTP subsystem instead.

Example: "/usr/bin/sudo -u root /usr/lib/openssh/sftp-server" starts the server as the root user.

UseSingleChannelDWORDEnabling this setting will prevent the drive from starting multiple SFTP channels. SFTP Drive by default will use one channel to read and write files in an asynchronous manner and another channel for synchronous operations such as enumerating files and folders, deleting files, and deleting folders.
  • 0 - Disabled (default)
  • 1 - Enable single channel mode
ConfirmPermissionsDWORDWhen this setting is enabled, SFTP Drive will always attempt to open the file/directory beforehand to verify the user has permission to perform the operation. This improves the experience in Explorer when navigating around the server's filesystem.

Note: Turning this off does not prevent permissions checking altogether. The server will always prevent reads and writes if the SFTP user does not have permission to read or write.

  • 0 - Disabled (default)
  • 1 - Confirm permissions

ServerProfileStringThis setting abstracts multiple different configuration settings into a single setting. When this setting is non-empty, the application will attempt to turn on all the required configuration settings based on the server name. The possible values of this setting are
  • moveit - Progress MOVEit Transfer

Additional values are reserved for future use.

DefaultFilePermissionsStringThis setting controls the file permissions of any new files created on the drive. SFTP Drive will create the file on the remote machine using the default mode mask of the SSH user. If this setting is enabled and non-empty, after the file has been created SFTP Drive will set the file's attributes to the specified permissions. The configuration setting supports a string of three numbers in base 8.

Default - 664

  • # owner: sftpuser
  • # group: sftpuser
  • user::rw-
  • group::rw-
  • other::r--

DefaultFolderPermissionsStringThis setting controls the permissions of any new folders created on the drive. SFTP Drive will create the folder on the remote machine using the default mode mask of the SSH user. If this setting is enabled and non-empty, after the folder has been created SFTP Drive will set the attributes to the specified permissions. The configuration setting supports a string of three numbers in base 8.

Default - 775

  • # owner: sftpuser
  • # group: sftpuser
  • user::rwx
  • group::rwx
  • other::r-x

SSHEncryptionAlgorithmsStringA comma-separated list containing all allowable encryption algorithms in order of preference. When this setting is non-empty, only the specified encryption algorithms will be negotiated.

aes256-ctr256-bit AES encryption in CTR mode
aes256-cbc256-bit AES encryption in CBC mode
aes192-ctr192-bit AES encryption in CTR mode
aes192-cbc192-bit AES encryption in CBC mode
aes128-ctr128-bit AES encryption in CTR mode
aes128-cbc128-bit AES encryption in CBC mode
3des-ctr192-bit (3-key) triple DES encryption in CTR mode
3des-cbc192-bit (3-key) triple DES encryption in CBC mode
cast128-cbcCAST-128 encryption
blowfish-cbcBlowfish encryption
arcfourARC4 encryption
arcfour128128-bit ARC4 encryption
arcfour256256-bit ARC4 encryption
aes256-gcm@openssh.com256-bit AES encryption in GCM mode.
aes128-gcm@openssh.com128-bit AES encryption in GCM mode.
chacha20-poly1305@openssh.comChaCha20 with Poly1305-AES encryption.

The following algorithms are enabled by default:

aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,arcfour256,arcfour128,arcfour,cast128-cbc,aes256-gcm@openssh.com,aes128-gcm@openssh.com,chacha20-poly1305@openssh.com

SSHMacAlgorithmsStringA comma-separated list containing all allowable message authentication algorithms in order of preference. When this setting is non-empty, only the specified MAC algorithms will be negotiated.

  • hmac-sha1
  • hmac-md5
  • hmac-sha1-96
  • hmac-md5-96
  • hmac-sha2-256
  • hmac-sha2-256-96
  • hmac-sha2-512
  • hmac-sha2-512-96
  • hmac-ripemd160
  • hmac-ripemd160-96
  • hmac-sha2-256-etm@openssh.com
  • hmac-sha2-512-etm@openssh.com
  • umac-64@openssh.com
  • umac-64-etm@openssh.com
  • umac-128@openssh.com
  • umac-128-etm@openssh.com

The following algorithms are enabled by default:

hmac-sha2-256,hmac-sha2-512,hmac-sha1,hmac-md5,hmac-ripemd160,hmac-sha1-96,hmac-md5-96,hmac-sha2-256-96,hmac-sha2-512-96,hmac-ripemd160-96,hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com

SSHKeyExchangeAlgorithmsStringA comma-separated list containing all allowable key exchange algorithms in order of preference. When this setting is non-empty, only the specified key exchange algorithms will be negotiated.

  • curve25519-sha256
  • curve25519-sha256@libssh.org
  • diffie-hellman-group1-sha1
  • diffie-hellman-group14-sha1
  • diffie-hellman-group14-sha256
  • diffie-hellman-group16-sha512
  • diffie-hellman-group18-sha512
  • diffie-hellman-group-exchange-sha256
  • diffie-hellman-group-exchange-sha1
  • ecdh-sha2-nistp256
  • ecdh-sha2-nistp384
  • ecdh-sha2-nistp521
  • gss-group14-sha256-toWM5Slw5Ew8Mqkay+al2g==
  • gss-group16-sha512-toWM5Slw5Ew8Mqkay+al2g==
  • gss-nistp256-sha256-toWM5Slw5Ew8Mqkay+al2g==
  • gss-curve25519-sha256-toWM5Slw5Ew8Mqkay+al2g==
  • gss-group14-sha1-toWM5Slw5Ew8Mqkay+al2g==
  • gss-gex-sha1-toWM5Slw5Ew8Mqkay+al2g==

The following algorithms are enabled by default:

curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group14-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha256,diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,ecdh-sha2-nistp256,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,ecdh-sha2-nistp384,ecdh-sha2-nistp521

SSHPubKeyAuthSigAlgorithmsStringThis setting specifies a list of signature algorithms that may be used when authenticating to the server using public key authentication. This applies only when public key authentication is performed by the client.

  • ssh-rsa
  • rsa-sha2-256
  • rsa-sha2-512
  • ssh-dss
  • ecdsa-sha2-nistp256
  • ecdsa-sha2-nistp384
  • ecdsa-sha2-nistp521
  • ssh-ed25519
  • x509v3-sign-rsa
  • x509v3-sign-dss

The following algorithms are enabled by default:

ssh-rsa,rsa-sha2-256,rsa-sha2-512,ssh-dss,ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-ed25519

CacheOnlyFilesString

A comma-separated list of filemasks that will not be created on the remote server. Note: This setting is only applicable when CacheDirectory is set. Any files matching the pattern specified by this setting will not be uploaded to the remote server but will be accessible to applications locally. This is useful in situations where applications may create temporary files that do not need to be uploaded.

The * wildcard character may be used. For instance to exclude all .tmp and .dat files a value of *.tmp,*.dat would be used. This setting only applies to files, it does not apply to directory names. This setting is not case sensitive.

NOTE: The value provided in this setting will affect only new files which are created directly and not the files which are existing on the storage then renamed or existing files which are deleted. If a file is renamed to an excluded value, then subsequent reading and writing will only be performed against the local copy.

CacheDirectoryString

The local directory where files will be stored temporarily during read and write operations. The default cache directory is C:\ProgramData\SFTPDrive.

Note: The default cache directory is visible to all local users on the machine.

CacheEnableDWORD

This setting controls whether bits and pieces of files will be stored on the local drive to be uploaded at a later time. The default value is 1 and files will be stored at the location specified by CacheDirectory and uploaded in the background.

Note: Specifying a value of 0 means that operations on files are performed over a live connection based on filesystem events.

CacheInfoValidityTimeDWORD

The time in seconds for which the current directory information is considered valid. When a file is created SFTP Drive will first check to see if the file already exists in the SFTP server. SFTP Drive will first check the cached listing for the directory. If the directory information is older than CacheInfoValidityTime a request will be made to the SFTP server to update the directory listing. If the directory information is newer than CacheInfoValidityTime it will be considered valid and will not result in a separate request to the SFTP server.

In cases where many new files are copied to a folder in a short period of time this can improve performance since it will reduce the number of requests made to the SFTP server. To disable this functionality set the value to 0. The default value is 30.

CacheLargeFileSizeMinimumDWORD

The minimum size of files in megabytes for which a multipart upload will be used. Files written to the virtual drive which exceed this size will be uploaded to the remote storage as a set of independent parts. This is most helpful for uploading large objects. The default value is 5 (5 MB).

CacheFileUploadDelayDWORD

The delay in seconds to wait after a file is idle before initiating an upload to the SFTP server.

A delay may be beneficial in cases where a file is repeatedly accessed. With a delay in place only one copy of the file will be uploaded after the file has been idle for the specified number of seconds. The default value is 5.
CacheFileUploadDelayThresholdDWORD

The maximum size in bytes of cached files that will be uploaded without waiting for CacheFileUploadDelay to lapse. If a file is smaller than the specified number of bytes it will be uploaded immediately. The default value is 1048576 (1 MB).

Note: Specifying a value of 0 means that this setting will not be used and CacheFileUploadDelay will apply to all files.

CacheEnabledForReadDWORD

This setting only applies when when Whether file content should be cached locally when an application reads the file content from the virtual drive. The default value is 0 and the file is not cached locally until the first write is performed.

Specifying a value of 1 means that files will be cached locally for read operations and write operations. If the remote files are very large this could significantly increase the amount of disk space used by the cache.

Note: This setting is only applicable if CacheEnable is set to true

CacheMaxUploadRetriesDWORD

The maximum number of retries for the operation. This setting is applicable when data is uploaded from the local cache to the SFTP server. If an operation related to the upload fails it will be retried up until the maximum number of retries specified in this setting. The default value is 3.

CacheConcurrentUploadFilesMaxDWORD

The maximum number of files being uploaded simultaneously. The default value is 8 meaning up to 8 files may be uploaded concurrently. Note that each file may use multiple connections to the server, see CacheConcurrentUploadThreadsPerFile for details.

CacheConcurrentUploadThreadsPerFileDWORD

The maximum number of parallel upload operations per file. If the file is a large file (greater than 5 MB) it will be uploaded using multiple threads to increase performance. This setting controls how many threads can be used to upload individual parts of the file. The default value is 8.

CacheConcurrentDownloadFilesMaxDWORD

The maximum number of files being downloaded simultaneously. The default value is 8 meaning up to 8 files may be downloaded concurrently. Note that each file may use multiple connections to the server, see CacheConcurrentDownloadThreadsPerFile for details.

Note: This setting is only applicable if CacheEnabledForRead is set to true

CacheConcurrentDownloadThreadsPerFileDWORD

The maximum number of parallel download operations per file. This setting controls how many threads can be used to download individual parts of the file. The default value is 8.

Note: This setting is only applicable if CacheEnabledForRead is set to true

CacheFileDeleteDelayDWORD

The number of seconds to wait before deleting an unused file from the cache.

After the specified number of seconds have passed if no further activity has taken place on the file it will be deleted from the cache. The default value is 5 seconds.
CachePreDownloadSmallFileCountDWORD

The number of small files to pre-download. The application will pre-download small files before they have been requested in order to speed up future requests.

For instance, if a read request is made for a.txt the application will download b.txt so that when a request is made for b.txt it can be returned quickly. The default value is 4.

Files are considered small if they are smaller in size than CachePreDownloadSmallFileSizeLimit. Files which match the criteria are downloaded alphabetically.

CachePreDownloadSmallFileSizeLimitDWORD

The maximum size of a file (in bytes) to be considered for pre-downloading.

This setting works in conjunction with CachePreDownloadSmallFileCount. The default value is 1048576 (1MB)
AuthTypeDWORDDetermines the type of authentication used to connect to the server:
  • 0 - Password
  • 1 - Public key
  • 2 - Keyboard-interactive
  • 3 - Multi-factor
  • 4 - Public key (Pageant)
  • 5 - Public key (Security Key)
  • 6 - Password + OTP (One Time Password)
CertStoreStringThe name of the certificate store for the client certificate
CertStoreTypeDWORDThe type of certificate store for this certificate
  • 0 - User
  • 1 - Machine
  • 2 - PFX File
  • 3 - PFX Blob
  • 4 - JKS File
  • 5 - JKS File
  • 6 - PEM Key File
  • 7 - PEM Key File
  • 8 - Public Key File
  • 9 - Public Key File
  • 10 - SSH Public Key Blob
  • 11 - P7B File
  • 12 - P7B Blob
  • 13 - SSH Public Key File
  • 14 - PPK File
  • 15 - PPK Blob
  • 16 - XML File
  • 17 - XML Blob
  • 18 - JWK File
  • 19 - JWK Blob
  • 20 - Security Key
CertStorePasswordStringIf the certificate store is of a type that requires a password, this registry setting is used to specify that password in order to open the certificate store.
CertSubjectStringThe subject of the certificate used for client authentication. The certificate subject is a comma separated list of distinguished name properties and values. For instance "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com".
ForceRenameDWORD

Determines whether or not to forcefully rename a file if the destination file already exists. By default, renaming a file will fail if the destination file already exists.

If enabled and the destination file already exists, the destination file will be renamed to have a temporary extension as a backup. The original file will be renamed to the destination file and the temporary file will be deleted. If the rename operation fails for any reason the temporary file is renamed back to the destination file so effectively no changes occur when the rename fails.

  • 0 - Disabled (default)
  • 1 - Enabled

HostStringContains the remote host that SFTP Drive will connect to.
PasswordStringContains the password for the SFTP server.
PortDWORDContains the port on the remote host that SFTP Drive will connect to.
QueryAvailableSpaceDWORDWhether to query the remote server for available space when connecting. Possible values are:
  • 0 - Disabled
  • 1 - Enabled (default)
RemoteRootTypeDWORDDetermines how the drive decides what folder to use as the root of the drive.
  • 0 - Server Root (/)
  • 1 - User's home folder (/home)
  • 2 - Specified folder (use RemoteRoot)
SecurityKeyAccountStringAn opaque token holding information about the certificate selected from the security key. This value is created by the application and should not be set manually.
SecurityKeyNameStringA friendly name of the chosen key. This is populated after selecting a key. For instance "PIV AUTH pubkey"
SecurityKeyPINStringThe encrypted PIN of the security key.
SecurityKeyPKCS11LibPathStringThe path to the library which implements the PKCS11 interface. This may be provided by the security key vendor, or may be an alternative implementation like OpenSC. For instance "C:\Program Files\OpenSC Project\OpenSC\pkcs11\onepin-opensc-pkcs11.dll"
SecurityKeySavePINDWORDWhether to save the PIN. If saved, the PIN is encrypted.
SignedSSHCertString

The CA signed client public key used when authenticating. When authenticating via public key authentication this setting may be set to the CA signed client's public key. This is useful when the server has been configured to trust client keys signed by a particular CA. For instance:

SignedSSHCert=ssh-rsa-cert-v01@openssh.com AAAAB3NzaC1yc2EAAAADAQABAAAB...")

The algorithm such as ssh-rsa-cert-v01@openssh.com in the above string is used as part of the authentication process. To use a different algorithm simply change this value. For instance all of the following are acceptable with the same signed public key:

  • ssh-rsa-cert-v01@openssh.com AAAAB3NzaC1yc2EAAAADAQABAAAB...
  • rsa-sha2-256-cert-v01@openssh.com AAAAB3NzaC1yc2EAAAADAQABAAAB...
  • rsa-sha2-512-cert-v01@openssh.com AAAAB3NzaC1yc2EAAAADAQABAAAB...

UseIPv6DWORDControls which IP version is used for the connection. These are the valid options:
  • 0 - Use IPv4 (default)
  • 1 - Use IPv6
  • 2 - Try IPv6, but fallback to IPv4 on failure.
UsernameStringContains the username for the SFTP server.

Tunnels

The following values can be configured independently for each tunnel, at HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22\SSHTunnels\{Tunnel Name}:

NameTypeDescription
TunnelNameStringA label for the daemon which will accept connections and tunnel data from the local machine to the forward host.
ForwardHostStringA hostname or IP address of the destination machine.
ForwardPortDWORDThe port on the destination machine to which data will be sent.
ListenHostStringA hostname or IP address of the interface to use to accept connections.
ListenPortDWORDThe ingress port for data to be tunneled.
SSHHostStringA hostname or IP address of the gateway machine. This server will project the data from the local machine to the destination machine and is sometimes called a "bastion host" or "jump host".
SSHPortDWORDThe port on the gateway machine used to establish the tunnel.
SSHUserStringThe username which is used to authenticate to the gateway machine.
SSHPasswordStringThe password which is used to authenticate to the gateway machine.
StoreTypeDWORDThe type of certificate store used to authenticate to the gateway machine.
  • 0 - User
  • 1 - Machine
  • 2 - PFX File
  • 3 - PFX Blob
  • 4 - JKS File
  • 5 - JKS File
  • 6 - PEM Key File
  • 7 - PEM Key File
  • 8 - Public Key File
  • 9 - Public Key File
  • 10 - SSH Public Key Blob
  • 11 - P7B File
  • 12 - P7B Blob
  • 13 - SSH Public Key File
  • 14 - PPK File
  • 15 - PPK Blob
  • 16 - XML File
  • 17 - XML Blob
  • 18 - JWK File
  • 19 - JWK Blob
  • 20 - Security Key
StoreStringThe name of the certificate store will be used to authenticate to the gateway machine.
StorePasswordStringIf the certificate used to authenticate to the gateway machine requires a password, this registry setting is used to specify that password in order to open the certificate store.

Trusted SSH Host Keys

The product maintains a list of trusted SSH host keys. When connecting to a new SSH host a prompt is displayed to the user asking whether to accept or reject the host key. If the host key is accepted the key and IP address of the host are stored in the list here.

Any time a connection is made to an SSH host the server's host key is checked against the list of trusted keys defined in this section.

The host keys are stored under HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\SFTPDrive\22\TrustedSSHHostKeys. Entries at this location will hold a string value for each host in the format [host]:[port], and the value being the fingerprint of the server.

The host key may also be manually set to "*" for specific hosts, indicating the server's host key is always to be trusted regardless of its value. Note SSH's security inherently relies on client verification of the host key. Setting the host key to "*" should be exercised with caution.

Shared Drives

SFTP Drive allows drives to be shared among all local users or restricted to the current user. This is controlled by the "Allow all users access to the drive" setting found in the Advanced tab of the Drive Configuration window. It is also controlled by the Shared registry setting for a particular drive (see Drives for more information). When this setting is enabled, the drive is accessible to all local users on the machine. When disabled, the drive is only accessible by the account under which SFTP Drive is running.

Accessible to All Users

When "Allow all users access to the drive" is enabled SFTP Drive creates a virtual drive accessible to all user sessions. The application maintains one connection to the server per drive and all file system operations that occur use the existing connection. Any user that interacts with the drive inherits the credentials of the connection to work with files on the drive. Settings for the application and drives can be specified in a subkey of the HKEY_LOCAL_MACHINE hive to indicate the settings apply system-wide to any user interacting with the drive.

Restricted to the Current User

When "Allow all users access to the drive" is disabled the drive is only accessible in the current user session. Attempting to access the drive from another user session will cause Windows to throw a "Cannot find drive." error message.

See Also: Isolated Mode

Isolated Mode

SFTP Drive can be launched with a command line flag to indicate all settings should be completely separate for each local user account. The /isolated flag controls this behavior (see Running SFTP Drive for usage examples). When this flag is specified each local user will be able to manage their own drive list and application settings. The user's list of drives and application settings will persist across logging in and logging out.

This flag will tell SFTP Drive to read application configuration and drive configuration from the HKEY_CURRENT_USER hive instead of the HKEY_LOCAL_MACHINE hive. When this flag is specified and a new instance is created, it is called an "isolated instance" or "HKCU instance". When a new instance is created without this flag it is called a "global instance" or "HKLM instance".

The default values of configuration settings are the same regardless of whether you are running an HKCU or HKLM instance. For example, drives are shared among all local users by default. It is a common pitfall to think an isolated instance will only create drives that are private - but that is not the case. To create a private drive in isolated mode turn off the "Allow all users access to the drive" setting as discussed in Shared Drives. Below is a table to illustrate the interaction between shared drives and isolated mode.

Launch mode Shared setting Description
Isolated Enabled Configuration is per-user and drives are accessible to everyone.
Isolated Disabled Configuration is per-user and drives are only accessible in the current user's session.
Normal Enabled Configuration is system-wide and drives are accessible to everyone.
Normal Disabled Configuration is system-wide but drives are only accessible in the current user's session.

Isolated mode is useful in environments where each user needs to mount a drive with their own credentials. Drives can be configured and started manually by each end user or via an automated logon script. This allows many isolated instances to be running at the same time but only one global instance can ever be running at a time. One important note: running as a Windows Service is not possible in an isolated instance.

Troubleshooting

If you are having problems with SFTP Drive, our support team is here to help. Visit https://www.nsoftware.com/support/submit.aspx to submit a ticket. Please be as detailed as possible about your issue. It is also helpful if you generate and send a log file to support@nsoftware.com.

How to Generate a Log File

  1. Navigate to the Settings tab.
  2. Enable Write Log to a File and specify a local file.
  3. Increase the Log Mode.
  4. Click the Save Changes button.
  5. Reproduce the issue.
  6. Click the Stop button.

Note that the length of time it takes for any operation is increased when Debug logging is enabled. The amount of data logged with this option enabled is substantial. We recommend enabling these settings for debugging purposes only.

Common Issues

Below you will find a list of common issues reported by our customers that you may find useful in troubleshooting a problem.

The Run as a Windows Service checkbox is enabled but drives are not connected upon startup.

All enabled drives should be connected automatically when the machine turns on, but there can be external factors which can cause this to fail. For instance, the system resources are not ready, the machine is multi-homed, policy of anti-virus software, etc.

When troubleshooting behavior with automatic start first ensure that the startup type is set to Automatic (Delayed Start) by opening the Service Control Manager, right-click the SFTP Drive service, and open the service properties.

If you have VPN software installed or the machine is multi-homed, then use Advanced Settings to configure the LocalHost setting in the registry. This setting should be set to the IP address of the network interface to use when connecting.

If neither suggestions help please gather an event log from the system which is failing and send it to us for analysis. This can be done by opening the Event Viewer, expand Windows Logs, then save the Application and System logs by right-click and Save All Events As....

Copying certain files causes a prompt specifying "The file XXX has properties that can't be copied to the new location"

The virtual drive created by SFTP Drive is of type exFAT. Certain NTFS specific functionality such as alternate data streams are not currently supported and may result in the warning above. Choosing to proceed with the operation when prompted by Windows is safe and does not affect the file content.

SFTP Drive fails to connect to a TLS-enabled FTP server

The drives mounted by SFTP Drive work exclusively with SFTP servers. TLS-enabled FTP servers are not currently supported by the application.

SSH connection failed: Connection failed: No connection could be made because the target machine actively refused it.

A connection refused error indicates a TCP-reset flag was received when the connection was initiated. This can mean no process is listening on the specified port, the port is being blocked by a firewall, or the IP address is incorrect.

SSH connection failed: Timeout.

A timeout error is thrown when the remote host does not respond after the specified amount of time in the Settings tab. It could indicate a firewall, antivirus, or proxy is dropping the connection.

SSH connection failed: Could not bind to LocalAddress.

A bind error indicates the application was not able to bind to the default networking interface. This can happen if the machine has multiple networking interfaces. To resolve the issue, set the LocalHost value of the Advanced Settings to the IP address of your default network interface.