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).

Prerequisites

SFTP Drive is supported on Windows 7 and Server 2008 R2 with SHA2 code-signing updates and above. The system needs to have KB976932 (Service Pack 1 of the mentioned systems) and KB4474419 (Security Update).

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:

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.

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.

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

SFTP Drive offers convenient ways to migrate application settings from one system to another. Please note that this migration pertains exclusively to your client settings and does not involve transferring the contents of the virtual drive.

Exporting Settings

To export your settings, follow these steps:

1. Navigate to the Settings tab within the application.
2. Click the Export link to initiate the settings export process.
3. 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, follow these steps:

1. Navigate to the Settings tab within the application.
2. click Import link to start the import process.
3. Specify the filename of the .ini file you want to load your settings from.

Note on Sensitive Information

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:

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

Drives

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

Tunnels

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

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.

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.

System error: No such host is known

No such host error is thrown when the system cannot resolve the endpoint address using the assigned network interface. This can happen if the remote address is malformed, if the default DNS server is misconfigured, if the proxy settings are is misconfigured, or if the system is using the wrong network interface.

Check the accessibility of the remote address from the client system using other means (e.g. using the ping utility). Check whether the behavior is specific to the conditions of your network by testing from a different network and system. If the machine has multiple networking interfaces, set the LocalHost value of the Advanced Settings to the IP address of your default network interface.