Documentation

6.11. SMB / Windows Share

An smb location provides access to an SMB (Server Message Block or Windows Share) server over TCP.

SMB versions 3 and 2 are supported, but version 1 is not. Access over UDP is not included either.

6.11.1. Introduction

The location only requires configuring the server address and credentials. The actual share names and paths used for a file transfer are defined as part of the transfer path configuration.

The communication with the SMB server is encrypted and all messages are signed. Contact us if you need access to legacy Windows shares that don't support encryption or message signing.

Warning

When accessing an Azure Files share authenticated using storage account key from outside the Azure cloud, it is highly recommended to secure your connection to the Azure cloud using private endpoints, site-to-site, or point-to-site VPN. Azure Files storage account key authentication is based on NTLM and is vulnerable to man-in-the-middle attacks.

Note

On-premises Active Directory Domain Services or Azure Active Directory Domain Services authentication methods via Kerberos are not yet supported.

6.11.2. Windows Share UNC path handling

The location only requires configuring the server address and credentials.

The actual share name and path used for a file transfer are defined as part of the transfer's configuration.

In this way, you can define multiple transfers to the same server without having to repeat the server name for each transfer.

Direct usage of UNC format paths is not supported. UNC paths can be translated into a format that is supported by SFTPPlus.

The goal is to handle Windows Share / SMB shares paths in a way that is consistent with accessing an FTP, SFTP or HTTP path.

For example, for handling a path like \qafs1.smb.example.comD$user-filesjohnD the configuration will look like this:

  • qafs1.smb.example.com - defined as part of the location's "address"

  • /D$/user-files/johnD - defined as part of transfer's source or destination path

6.11.3. name

Default value

Empty

Optional

No

From version

2.8.0

Values
  • Any text.

Description

Human-readable short text used to identify this location.

6.11.4. description

Default value

Empty

Optional

Yes

From version

2.8.0

Values
  • Any text.

Description

Human-readable text that describes the purpose of this location.

6.11.5. type

Default value

''

Optional

No

From version

2.6.0

Values
  • filesystem - Local file system.

  • sftp - SFTP protocol v3 over SSH v2.

  • ftp - FTP protocol without any encryption.

  • ftpse - Explicit FTPS protocol.

  • ftpsi - Implicit FTPS protocol.

  • webdavs - WebDAV over HTTPS.

  • as2 - AS2 over HTTP or HTTPS

  • azure-file - Azure File Service.

  • smb - SMB / Windows Share

Description

This option specifies the type of the location. Each type has a set of specific configuration options

6.11.6. idle_connection_timeout

Default value

300

Optional

Yes

From version

3.0.0

Values
  • Number of seconds

  • 0

Description

This controls the automatic disconnection from the remote server after the location has not received any file transfer operation requests for the configured number of seconds.

Keep-alive command requests are not counted as file transfer operations. The connection gets automatically disconnected if keep-alive is the only command requested in the configured interval.

Disconnected locations automatically reconnect when a new file transfer operation request is made. For example, when a new file needs to be transferred to the remote server.

If the remote peer closes the connection before the configured timeout, the connection is left closed. It gets automatically reconnected when a new file transfer operation is requested.

Set to 0 to always keep the connection active, by forcing re-connection when the remote server closes the connection.

Note

The idle_connection_timeout is the maximum number of seconds before closing an idle connection to the server. If the remote server decides that the connection is idle and closes the connection, SFTPPlus doesn't try to "challenge" the server, leaving the connection closed. The connection is automatically reopened next time a file needs to be transferred.

6.11.7. idle_connection_keepalive_interval

Default value

0

Optional

Yes

From version

3.0.0

Values
  • Number of seconds

Description

Send a keep-alive command every N seconds to avoid having the connection disconnected by the other peer due to inactivity.

Set to 0 to disable keep-alive commands.

The keep-alive command does not reset the idle connection timeout,

6.11.8. connection_retry_count

Default value

12

Optional

Yes

From version

3.9.0

Values
  • Number of retries

Description

Number of times to retry connection to the location, when the initial connection fails.

Set to 0 to not retry.

6.11.9. connection_retry_interval

Default value

300

Optional

Yes

From version

3.9.0

Values
  • Number of seconds

Description

Number of seconds to wait between connection attempts.

Set to 0 to retry right away without any delay.

6.11.10. address

Default value

Empty

Optional

No

Values
  • Host name or IP address of the server.

From version

4.13.0

Description

Address of the remote SSH server. IP or DNS name.

If you are using Azure Files the address will have the following format: ACCOUNT_NAME.file.core.windows.net where ACCOUNT_NAME is replaced with your Azure Storage account name.

6.11.11. port

Default value

445

Optional

No

Values
  • Number, greater than 0.

From version

4.13.0

Description

Port number of the remote server.

6.11.12. username

Default value

Empty

Optional

No

From version

4.13.0

Values
  • Text.

Description

Username or storage account name used to authenticate to the remote server.

Anonymous (guest) access is not yet supported. Contact us if you need support for connecting to a Windows Share without a username and password.

6.11.13. password

Default value

Empty

Optional

No

From version

4.13.0

Values
  • Plain text password.

  • Empty

Description

This option specifies the password or key used to connect to the remote server. It is provided in plain text.

6.11.14. require_encryption

Default value

'yes'

Optional

No

From version

4.16.0

Values
  • yes.

  • no.

Description

This option defines whether SFTPPlus requires SMB encryption when connecting to the remote share.

With modern servers it is recommended to keep this option set to yes to make use of the highest level of available security.

On Windows 2008 and Windows 7 or older version of Windows, SMB encryption is not supported. To connect to these shares you will need to set this configuration to no.