Introduction

Welcome to S3 Drive, a powerful solution for accessing remote resources as if they were local drives, eliminating the need to download and upload files you need to work with. Easily manage remote files stored on any S3-compatible service from your favorite file management utility or the command line. Choose from the list of built-in providers or add your own provider to get started. Configure the access credentials and click the "Start" button to start browsing the filesystem.

Features

  • Work with a remote file system as if it were a local disk drive.
  • Support for multiple drive configurations.
  • Run as a Windows service or a desktop application.
  • Upload and download files via your favorite file manager, such as Windows Explorer.
  • Supports all common directory and file operations such as move, copy, and rename.
  • Support for all common providers including:

    • Amazon S3
    • Backblaze B2
    • Cloudflare R2
    • DigitalOcean Spaces
    • IBM Cloud Object Storage
    • IDrive e2
    • Linode
    • MinIO
    • Oort DSS
    • Oracle Cloud Storage
    • Scality
    • Seagate Lyve Cloud
    • Wasabi
    • Any S3 Compatible Service (Custom Provider)

Additional Information

You will always find the latest information about S3 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 S3 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 S3 Drive

S3 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

S3 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:

/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 S3 Drive service
/servicestop Stops the S3 Drive service
/isolated Launches S3 Drive in Isolated Mode
/registerservice Registers the S3 Drive service with Windows
/unregisterservice Unregisters the S3 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 S3 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 s3drive.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 s3drive.dll start --mount-point /path/to/mount/point --provider amazons3 [--region us-east-1] --bucket test --access-key VALUE --secret-key VALUE

The following parameters are available with explicit drive creation.

--mount-point Specifies the path on the local machine where the filesystem will be mounted.
--provider Specifies the desired storage provider for your data. Available values are amazons3, backblazeb2, cloudflarer2, digitalocean, ibm, linode, oortdss, oracle, seagatelyvecloud, and wasabi.
--region (Optional) Defines the region used for communication with the storage provider.
--bucket Specifies the bucket to serve as the top-level folder for the drive.
--access-key Defines the access key for the account.
--secret-key Defines the secret key for the account.
-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 s3drive.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 s3drive.dll stop

Status of the Drive

The drive status can be queried using the following command.

dotnet s3drive.dll status

Drive Help

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

dotnet s3drive.dll help
Example Configuration Settings

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

# S3 Drive Example Configuration
#
# This is the S3 Drive configuration file. See the online 
# documentation for more information.
#
#   https://cdn.nsoftware.com/help/NBH/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/s3drive/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="S3Drive"

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

# Determines whether the drive will be connected.
#Enabled=True

# Defines a bucket or object on the server that will serve as
# a root folder of the drive. If needed, a path portion can be 
# specified after the bucket name. For example: bucket/path/to/object.
Bucket="bucket"

# 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"

# Defines the provider and region to use when connecting to the S3 storage provider. 
# To use a custom provider, define the URL configuration setting below. 
# Valid options are :
#   amazons3 (default)
#   backblazeb2
#   cloudflarer2
#   digitalocean
#   ibm
#   linode
#   oortdss
#   oracle
#   seagatelyvecloud
#   wasabi
#Provider="amazons3"
#Region="us-east-1"

# Defines credentials to connect to the S3 storage provider. 
AccessKey="YOUR_ACCESS_KEY"
SecretKey="YOUR_SECRET_KEY"

# Optionally define the URL to connect to the provider.
# By default the application will use the appropriate URL for the 
# provider and region specified. This setting may be used to override
# the default value.
#URL="https://s3.us-east-1.amazonaws.com"

# Defines an account id for authenticating to certain service providers. 
# This is only applicable to CloudflareR2.
#AccountID="" 

# Defines the settings to authenticate via role-based session with the Amazon
# provider using SAML identity provider for authentication. 
# The endpoint should be the ADFS endpoint to make the SAML request. When 
# set, the application will make a GET request to this endpoint to get a SAML
# response. This must be set alongside AssumeRoleARN, ADFSRelyingParty.
#ADFSSTSEndpoint=""
#ADFSRelyingParty=""
#AssumeRoleARN=""
#AssumeRoleDuration=0
#AssumeRolePrincipalARN=""

# Defines the settings to allow authentication via credentials file. The profile 
# for authentication will be parsed from the "credentias" file managed by AWS CLI.
#   NOTE: This setting is only applicable when UseAWSProfile is enabled. By default, 
#   the AWSProfileDir is stored under $HOME/.aws
#AWSProfile="default"
#AWSProfileDir=""

# 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 S3 server. 
#CacheInfoValidityTime=30

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

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

# Specifies the location on disk where bits and pieces of files will be stored 
# and uploaded at a later time. This allows random writing to be supported.
#   NOTE: By default, the cache is stored in $HOME/.nsoftware/S3Drive/cache/cli_provider_bucket 
#   where "provider" and "bucket" will be replaced with the values provided to the corresponding settings in this file. 
#   If a drive name is supplied, the cache directory will be $HOME/.nsoftware/S3Drive/cache/drivename.
#CacheDir=""

# 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. 
#CacheEnbledForRead=True

# 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 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 minimim size of a file in megabytes for which the application should 
# initiate a multipart upload. 
#CacheLargeFileSizeMinimum=5

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

# Specifies a comma-separated list of filemasks that will not be created. Any file
# which matches the pattern will not be uploaded but will remain accessible on the drive.
#   NOTE: The value provided in this setting will affect only new files, will not affect 
#   files already on the storage, or renamed, or deleted. 
#CacheOnlyFiles=""

# 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

# Specifies whether the application should authenticate by using the IAM role attached
# to the instance and obtain credentials from the Instance Metadata Service. 
#   NOTE: When IMDSVersion is 1 then the older request/response scheme will be used. The
#   settings are only applicable when the UseEC2RoleCredentials setting is enabled.
#IMDSVersion=2
#IMDSSessionDuration=21600

# Defines a namespace for authenticating to certain service providers. 
# This is only applicable to Oracle Cloud.
#Namespace=""

# Determines whether the drive is accessible by other users of the system.
# When enabled, the drive will be shared with all users of the system. 
# This setting is disabled by default. 
#   NOTE: This setting also needs the setting user_allow_other set in /etc/fuse.conf.
#Shared=False

# Determines the signing standard in outbound requests. Specify a 
# value of 2 to use the older signing standard. 
#SignatureVersion="4"

# Defines whether authentication will be attempted as an unauthenticated user.
#UseAnonymousAuthentication=False

# Defines whether authentication will be attempted using an Amazon credentials file. 
# See AWSProfile and AWSProfileDir for more information. 
#UseAWSProfile=False

# When the application is running within an Amazon EC2 instance, this can be set 
# to authenticate requests using the IAM role attached to the instance.
#UseEC2RoleCredentials=False

# Specifies whether to use server side encryption when objects are uploaded. By 
# default server side encryption will not be used. 
#UseServerSideEncryption=False

# Specifies whether to use TLS to communicate with the server. 
#UseSSL=True

# Specifies that the application should use the accelerated endpoint for 
# transfers to the Amazon S3 provider.
#   NOTE: The bucket must be configured to allow transfer acceleration.
#UseTransferAcceleration=False

# Defines whether the buckets are addresses in the URL using the S3 Virtual
# Hosting format. When set to False, path-style addressing is used instead. 
#UseVirtualHosting=True

# Controls 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.
#UseIPv6=0

Drive Management

The Start and Stop buttons provide the basic functionality of S3 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 S3 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.
  • Select the storage provider, such as Amazon S3.
  • Enter your access key in the Access Key field.
  • Enter your secret key in the Secret Key field.
  • Use the Bucket dropdown list to select the desired bucket.
  • The Test S3 Connection button will verify the connection to the S3 provider can be successfully established. When configuration is complete press OK to complete the drive configuration.
  • Optional Settings:

    • The Region field shows the current bucket's region and may optionally be set. In most cases there is no need to modify this value.
    • The Sub Folder setting may optionally be set to a folder within the bucket to be used as the drive root. For instance MyPictures/Birthday. This setting is not required.
    • 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.

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.

Provider and Region Management

The ... buttons next to the Provider and Region settings open a separate dialog to manage the available list of providers and their supported regions. When using custom providers, for instance MinIO or Ceph, this dialog may be used to add the necessary connection information. This dialog may also be used to add new regions to existing providers. For more details see the Provider Management page.

Provider Management

The Provider Management dialog provides a way to add additional S3-compatible providers, add new regions to existing providers, and otherwise manage the available providers and regions within the application.

To access the Provider Management dialog, from the Drives tab of the application select a drive and press the Edit... button. From the drive configuration page, click the ... button next to the Provider or Region property to open the Provider Management dialog.

Managing Providers

The Provider section of the Provider Management page defines the services available to the application. Both the built-in providers and the custom providers are shown here. All the providers on this list will be available in the Provider dropbox of the drive configuration page.

The Region section of the Provider Management page lists the regions of the selected provider. The regions will available in the Region dropbox of the drive configuration page. The corresponding New..., Edit..., and Delete buttons may be used to manage providers or regions.

Adding a New Provider

To add a new provider click New... and specify the friendly name of the provider and the endpoint format.

Provider is the friendly name of the service. This name will be added to the Provider dropdown list on the drive configuration page.

Endpoint Format specifies the URL of the service. If the provider supports multiple regions, use the %region% macro in the URL to represent the location where the region name should be substituted. If the service does not contain multiple regions simply do not include the placeholder, for instance a value of 10.0.1.15:9000 for a MinIO or Scality service is valid.

Adding a New Region

To add a new region to an existing provider click New... in the Region section.

Display Name is the friendly name of the region. This name will be added to the Region dropdown list on the drive configuration page.

Region is the region code which will be used in the URL when making requests. For instance us-east-1.

The Endpoint field displays the endpoint for the specific region, based on the endpoint format defined for the provider. This field is informational only and cannot be set.

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

Use SSL/TLS

This setting specifies whether SSL/TLS is enabled for the connection. The default value is enabled.

Use Virtual Hosting

This setting specifies whether the buckets are addresses in requests using the S3 Virtual Hosting format. This is enabled by default, and recommended unless there is a specific reason to disable this setting (for instance when using a custom provider).

Cache Settings

See Caching Information for more information.

Cache Directory

This setting specifies the location on disk where data will be stored. This is populated automatically, but may be changed if desired.

Max Concurrent Uploads

This setting specifies the maximum number of simultaneous upload operations that can be in progress at any time. The default value of 8 should work well in most cases. Large values in this setting will increase the number of simultaneous threads in the upload operation.

Max Concurrent Downloads

This setting specifies the maximum number of simultaneous downloads that can be in progress at any time. The default value of 8 should work well in most cases. Large values for this setting will increase the number of simultaneous threads in the download operation. Note: Using a large value may result in intermittent errors from the S3 service which will result in the upload/download operation being retried.

Enable Cache For Reads

This setting controls whether the requested content will be stored locally to speed up subsequent read operations against the files.

Directory (Metadata) caching

This setting controls the lifetime of files and directories returned during directory enumeration. Additionally, it controls the lifetime of metadata serviced from the cache. Low values for this setting means the cache contents expire quickly and will be fetched from remote storage more frequently. High values for this setting will provide a more responsive experience browsing the virtual drive. The default vaule of 30 seconds should work well in most cases.

Import and Export

S3 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 of the 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 S3 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.
  • 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. In S3 Drive, caching will help to ensure file content is uploaded to the remote machine.

The S3 REST API does not support writing a few bytes to a specific offset on an existing file. To support randomly writing files and the propagating changes to S3, we created a file-based cache which holds pieces of files on disk and uploads them once the modifications are complete.

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.

S3 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%\S3Drive\<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 S3 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.

If the file has any chunks which have not been read or modified before, then S3 Drive uses the CopyParts S3 API call to fill in the content of the new file with existing file data on S3.

File Information

The OS will ask for file information frequently. S3 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. This is primarily helpful at the S3-protocol level for deletion performance.

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

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

Shared Drives

S3 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 S3 Drive is running.

Accessible to All Users

When "Allow all users access to the drive" is enabled S3 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

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

Advanced Settings

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

The following keys hold configuration information:

Registry KeyApplicable Settings
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22Global settings for the application.
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\DrivesDrives hold drive specific settings.
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\ProvidersProviders stores provider and region settings.
HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\ContentTypesContent Types holds a mapping of common file extensions to MIME Content-Type values used when uploading files.

The following values can be configured within the root HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\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 S3 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 S3 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) S3 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 S3 Drive will ask for registry permissions if it does not have them when it tries to write to the registry.
  • 0 - S3 Drive will not ask for registry permissions, instead bringing up a UAC dialog for one-time access.
  • 1 - S3 Drive will ask to be granted registry permissions. If granted, UAC access will not be required in the future. (default)
RotateLogDaysDWORDSpecifies how many days S3 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 S3 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).

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

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 S3 Drive will use to connect to the proxy.
ProxyPasswordStringSpecifies the password that S3 Drive will use to connect to the proxy.
ProxyPortDWORDSpecifies the port that S3 Drive will use to connect to the proxy.
ProxyTypeDWORDSpecifies the type of proxy that S3 Drive will connect to.
  • 0 - None (default)
  • 1 - Tunnel
  • 2 - SOCKS4
  • 3 - SOCKS5
ProxyUsernameStringSpecifies the username that S3 Drive will use to connect to the proxy.
ReconnectAttemptsDWORDSpecifies the number of times S3 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 S3 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\S3Drive\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 S3 Drive is started.
  • 0 - Disabled
  • 1 - Enabled
IndexDWORDThe position of the drive in the list of drives.
OpenRemoteFolderDWORDDetermines whether or not S3 Drive will automatically open a folder after mounting the drive.
  • 0 - Disabled
  • 1 - Enabled
OpenSpecifiedFolderStringContains the folder that S3 Drive will open if OpenRemoteFolder is enabled.
ProxyHostStringSpecifies the host that S3 Drive will use to connect to the proxy.
ProxyPasswordStringSpecifies the password that S3 Drive will use to connect to the proxy.
ProxyPortDWORDSpecifies the port that S3 Drive will use to connect to the proxy.
ProxyTypeDWORDSpecifies the type of proxy that S3 Drive will connect to.
  • 0 - None (default)
  • 1 - Tunnel
  • 2 - SOCKS4
  • 3 - SOCKS5
ProxyUsernameStringSpecifies the username that S3 Drive will use to connect to the proxy.
ReadOnlyDWORDDetermines whether or not S3 Drive will mount the drive in read-only mode.
  • 0 - Disabled (default)
  • 1 - Enabled
RemoteRootStringContains the folder on the server that S3 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

CacheOnlyFilesString

A comma-separated list of filemasks that will not be created on the remote server. 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\S3Drive.

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

CacheInfoValidityTimeDWORD

The time in seconds for which the current directory information is considered valid. When a file is created S3 Drive will first check to see if the file already exists in the S3 provider. S3 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 S3 provider 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 S3 provider.

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 S3 provider. 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 S3 provider.

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.

CacheMaxUploadRetriesDWORD

The maximum number of retries for the operation. This setting is applicable when data is uploaded from the local cache to the S3 provider. 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 the S3 multipart upload operation 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)
AccessKeyStringThe AccessKey used to authenticate to the S3 provider.
AWSProfileStringThis setting, if non-empty, must contain the name of the AWS CLI profile whose authentication and (optionally) region information the application should use to communicate with the server. To use the default profile, set this setting to default. Refer to the following pages of the AWS CLI documentation for more information about AWS profiles, and the credentials and config files used to store them:

The application supports key-based credential profiles; i.e., those which include the aws_access_key_id, aws_secret_access_key, and (optionally) aws_session_token elements. Role-based profiles are not supported at this time.

In addition to the authentication-related elements mentioned above, the application also supports the region element, if it is present in the specified profile.

The application searches for the specified profile's information in the credentials and config files. The AWSProfileDir setting can be used to configure the directory where the application looks for these files. If the aforementioned files do not exist, or the specified profile cannot be found or is missing information, an error will occur.

AWSProfileDirStringThis setting specifies the directory that the application should check when attempting to locate the AWS CLI credentials and config files. This setting is only used if the AWSProfile setting is non-empty.

By default, this setting is empty, which will cause the application to check the default location used by the AWS CLI: an .aws directory in the current user's home directory; i.e., %UserProfile%\.aws (Windows) or ~/.aws (Linux/macOS).

SecretKeyStringThe encrypted SecretKey used to authenticate to the S3 provider.
EnableReadConflictDetectionDWORD

Whether conflict detection is performed when reading files. As files are read by applications, individual sections of the file may be requested. If another entity uploads a new version of the file to the S3 provider, then applications using the drive will not be aware the content has changed. When future read requests are performed, data from the new version of the file will be retrieved which may cause corruption.

When this setting is enabled (default) if a file is changed remotely any future read requests will fail and the file will be considered conflicted locally until resolved manually through the main window of the application.

EnableWriteConflictDetectionDWORD

Whether conflict detection is enabled when writing files. As files are written by applications, only the modified sections of the file are cached locally. When the file is persisted to S3 the modified sections of the file are combined with the pre-existing file data on S3. This operation may cause corruption if the pre-existing file data on S3 is changed by another entity before the upload completes.

When this setting is enabled (default) if a file is changed remotely the write operation will fail as it may cause corruption. The file will be considered conflicted until resolved manually through the main window of the application.

NOTE: This setting only applies when modified sections of a file are combined with existing file data on S3. For instance, when an application modifies part of a file stored on the drive. If the entire file contents are written to the drive, the entire file will be uploaded to the S3 server and will overwrite any version of the file which exists on the server already.

FragmentSizeDWORDThe part size to use when uploading a new object.
IMDSSessionDurationDWORD

This setting allows configuring the session time to live header sent to the metadata service. It governs the amount of time which the same session token can be used for subsequent requests. The default is 21600 seconds.

IMDSVersionDWORD

When the application is using the IAM role attached to the instance as security credentials, this configuration setting allows specifying the Instance Metadata Service version.

The default value is 2 and a session-oriented method will be used to retrieve temporary security credentials. When this setting is set to 1, a request/response model will be used instead. Please see "Configuring Instance Metadata Service" in the Amazon AWS Documentation for more information.

SignatureVersionString

Amazon S3 provider only. If specified, this determines the signing standard in outbound requests. For an overview of the available signing standards please see "Signing AWS API Requests" in the AWS Documentation.

By default, the signing version is 4. In SigV4, the signing key is derived from the credential scope string and will not be sent along in the request. Specifying a value of 2 means that the older Signature Version 2 will be used instead. Please note that SigV2 is deprecated and is no longer supported by Amazon.

RegionStringThe region of the provider to which requests will be made. For instance us-east-1.
URLStringThe URL of the S3 endpoint where connections will be made.
UseEC2RoleCredentialsDWORD

When the application is running within an Amazon EC2 instance, this setting can be set to authenticate requests using the IAM role attached to the instance using temporary credentials obtained from the instance metadata service. The IMDSv2 protocol is used by default. Please see the IMDSVersion configuration setting for more information.

In order for the application to be able to auto-obtain authentication credentials, the EC2 instance must have an "instance profile" with an appropriate IAM role attached to it. Refer to the "Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances" page in the Amazon IAM documentation for more information.

  • 0 - IMDS will not be used (default).
  • 1 - IMDS will be used.

UseIPv6DWORD

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

UseTransferAccelerationDWORD

When the bucket allows transfer acceleration, this config can be set to use the accelerated endpoint for transfers.

  • 0 - Transfer acceleration will not be used (default).
  • 1 - Transfer acceleration is enabled.

UseServerSideEncryptionDWORDWhether to use server side encryption when objects are uploaded. Possible values are:
  • 0 - Server side encryption will not be used (default).
  • 1 - Server side encryption is enabled.
UseSSLDWORDWhether requests to the S3 provider use SSL. Possible values are:
  • 0 - SSL will not be used.
  • 1 - SSL will be used for all requests (default).
UseVirtualHostingDWORDWhether the buckets are addresses in requests using the S3 Virtual Hosting format. This is enabled by default, and recommended unless there is a specific reason to disable this setting (for instance when using a custom provider). Possible values:
  • 0 - Virtual hosting is not used. Instead the path style addressing is used.
  • 1 - Virtual hosting is used (default - recommended).
UseAsynchronousTransferModeDWORDIf enabled, uploads and downloads will use multiple threads to increase the overall performance of the operation. Delete operations are batched and other areas are adjusted to increase overall performance. When enabled some operations are performed in the background and make use of a memory-based cache. Possible values:
  • 0 - Disabled (default)
  • 1 - Enabled
ProviderStringThis setting stores the name of the S3 service provider. To add a new provider or custom provider, see the instructions on the Provider Management page.
NamespaceStringThis setting stores the lowest-level subdomain in the connection URL. It is primarily used with Oracle Cloud as the provider.

Example: "abcdefg". This value will create a connection URL in the following format: https://abcdefg.compat.objectstorage.us-ashburn-1.oraclecloud.com

AccountIDStringThis setting stores the Account ID when authenticating to certain service providers. It is primarily used with the CloudflareR2 service provider.

Refer to the find zone and account IDs page of the Cloudflare R2 documentation for instructions on how to find your account ID.

AutoFixCaseDWORDThis setting determines whether the application will perform casing conversion on incoming filesystem requests in order to match such requests against files stored on the virtual drive. Possible values are:

  • 0 - Disabled (default)
  • 1 - Enabled

If this setting is disabled (default), and applications using the virtual drive perform casing conversions, our drive may be unable to match the target of the operation with an item on the virtual drive. This can result in the the Windows error Location is not available.

When this setting is enabled, the application will automatically fix the casing of incoming requests by those applications, potentially resolving the mentioned error. This extra step will translate provided paths to real paths and may result in additional requests to the server.

Note: Use with caution and only if necessary. Enabling this setting may cause performance issues. In almost all cases, this setting should remained disabled.

Providers

S3 Drive stores provider and region information in a tree in the registry. In most cases there is no need to manage these settings directly within the registry. Providers and regions can be managed from the application directly from the Provider Management dialog. See Provider Management for details.

Providers

A registry key is automatically created for each provider supported by the application. These are created at the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\20\Providers\{ProviderName}

The following values are applicable to the providers at this path:

NameTypeDescription
EndpointFormatString

The endpoint URL format for the provider with optional region placeholder. If the provider supports multiple regions use %region% in the URL to represent the location where the region will be inserted. For instance: s3.%region%.amazonaws.com.

Note: If the service does not contain multiple regions simply do not include the placeholder, for instance a value of 10.0.1.15:9000 for a MinIO service is valid.

Regions

Regions for each supported provider are specified in a sub-key of the provider key. These are created at the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\Providers\{ProviderName}\Regions

Each region is listed as a separate value in the above path. The value should be a String type, where the value name is the region to use in the URL and the value data is the friendly name which will be displayed to the user in the dropdown when creating the drive. For instance:

NameTypeData
us-east1StringUS East (N. Virginia)

Content Types

S3 Drive automatically sets the MIME Content-Type on files during upload based on the file extension. For instance a file ending in .txt will use a Content-Type of text/plain.

If desired, the Content-Type mapping may be modified for an existing extension, or a new mapping for a new extension may be added. Note that extensions must include the '.', for example .txt. If a mapping is not found for the file extension the Content-Type will not be set explicitly. The mapping between file extensions and Content-Types is defined by name value pairs in the registry at the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\ContentTypes

The following values are applicable at this path:

NameTypeDescription
{Extension}String

The standard MIME Content-Type, for example text/plain.

Trusted Certificates

S3 Drive stores information about trusted SSL certificates at the location noted below. In most cases there is no need to manage these settings directly within the registry.

When establishing a connection to the configured host the trust of the SSL certificate is determined by the Windows security libraries. If the certificate is not trusted on the system a dialog is displayed and the certificate may be explicitly accepted, thereby overriding the system trust. In this case the server's certificate is base64 encoded and stored in the registry for future connections. These are created at the following path:

HKEY_LOCAL_MACHINE\SOFTWARE\nsoftware\S3Drive\22\TrustedCertificates

The following values are applicable at this path:

NameTypeDescription
{HostName}String

The value name is the hostname of the server for which the certificate was manually accepted. For instance my.bucket.s3.us-east-1.amazonaws.com. The value data is the base64 encoded certificate that was manually accepted.

Troubleshooting

If you are having problems with S3 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 S3 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 S3 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.

Does regularly clearing the cache improve upload and download speeds?

The S3 Drive cache does not behave like the cache in a web browser, and "clearing the cache" is not something that will help with transfer speeds. S3 Drive manages the cache for you, so you should never need to perform maintenance on the cache to keep it working efficiently. Slow transfer rates could stem from environmental factors outside of S3 Drive. See Caching Information for more details.

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

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

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