SMB Share Connector

When to use this connector

Use this connector to create Flows that work with files in SMB Share.

Create a Connection

Step 1. In the Connections window, click +, and type in smb.

Step 2. Select SMB Share.

Step 3. Enter Connection parameters.

Connection parameters

• Host: SMB Share computer name, hostname, or IP address. Example: etlworks.
• Share Name: the SMB Share name. Example: test. 
• Directory: the directory containing the files. This parameter is optional. If it is empty the connector will work with files in the SMB Share root directory.
• Note: The fully qualified network path to the files in the SMB Share is calculated as //Host/Share Name/Directory. Example: //etlworks/test/inbound.
• Files: the actual file name or a wildcard file name, for example, *.csv.
• User: username.
• Password: password.
• Domain: the optional domain name.
• Authentication Method: NTLM (default) or Kerberos. NTLM preserves the existing behavior and authenticates with User, Password, and Domain. Kerberos authenticates with the Kerberos fields below and does not fall back to NTLM. Available since 9.9.12. See Kerberos authentication.
• Kerberos Credentials: used only with Kerberos. Password (default) uses the Password field, Keytab uses the Kerberos Keytab file, and Ticket cache uses the Kerberos Ticket Cache file. Keytab and ticket-cache files live on the Etlworks execution host, not in the browser.
• Kerberos Principal: used only with Kerberos, for example user@EXAMPLE.COM. Required for the Password and Keytab credential types. If omitted, the connector uses User when it already contains @; otherwise it combines User with Domain as User@Domain — in that case Domain must be the Kerberos realm (normally uppercase), not a NetBIOS domain name. With Ticket cache, leave User and Kerberos Principal blank to select the cached identity.
• Kerberos Keytab: used only with the Keytab credential type. Absolute path to a keytab file readable by the Etlworks process, for example /secure/etlworks.keytab. Protect it like a password.
• Kerberos Ticket Cache: used only with the Ticket cache credential type. Absolute path to a file cache containing a valid TGT. Leave blank to use the JVM default cache lookup; an explicit file cache is preferable because native OS caches are not universally accessible to Java.
• SMB Dialect: SMB Dialects are simply significant versions - just like dialects within human languages - that allow a client and server to agree on conversation behaviors. For example, the SMB 3.1.1 dialect came with Windows 10 and Windows Server 2016. These dialects allow the assignment of various capabilities like encryption, signing algorithms, multichannel connections, etc. When the SMB client initially connects to a destination server, it negotiates the matched and required set of capabilities.
• DSF Namespace: DFS (Distributed File System) Namespaces is a role service in Windows Server that enables you to group shared folders located on different servers into one or more logically structured namespaces.
• Multi Protocol Negotiation: if enabled the connector will attempt multi-protocol negotiation when connecting to the SMB share.
• Signing Required: SMB signing (also known as security signatures) is a security mechanism in the SMB protocol. SMB signing means that every SMB 3.1. 1 message contains a signature that is generated by using the session key and the Advanced Encryption Standard (AES) algorithm. 
• SMB Encryption: Default preserves the existing client behavior; Required enforces SMB 3.x encryption for the session. Use Required together with an SMB 3.x dialect for Azure Files. The server must allow an encryption cipher supported by the client; SMB 3.0 with AES-128-CCM is a compatible combination. Available since 9.9.12.
• Add Suffix When Creating Files in Transformation: you can select one of the predefined suffixes for the files created using this Connection. For example, if you select uuid as a suffix and the original filename is dest.csv, Etlworks will create files with the name dest_uuid.csv, where uuid is a globally unique identifier such as 21EC2020-3AEA-4069-A2DD-08002B30309D.

Note: This parameter works only when the file is created using source-to-destination-transformation. Read how to add a suffix to the files created when copying, moving, renaming, and zipping files.

• File Processing Order: Specifies the order in which source files are processed when using wildcard patterns in ETL and file-based flows (e.g., copy, move, delete). The default setting is Oldest, meaning files are processed starting with the oldest by creation or modification time. Choose from various criteria such as file age, size, or name to determine the processing sequence:
  • Disabled: wildcard processing is disabled,
  • Oldest/Newest: Process files based on their creation or modification time, Ascending/Descending: Process files in alphabetical order, Largest/Smallest: Process files based on their size. 

Kerberos authentication

Since 9.9.12, the SMB Share connector supports native Kerberos authentication. Set Authentication Method to Kerberos and choose a credential source with Kerberos Credentials. Kerberos uses a per-connection login with no NTLM fallback, and it does not change the JVM-wide Kerberos configuration. Existing connections remain NTLM unless explicitly changed.

Execution host prerequisites:

• The host that actually runs the flow — including remote Integration Agents — needs working Kerberos realm/KDC discovery, DNS, synchronized time, access to the KDC (normally TCP/UDP 88), and SMB access to the share on TCP 445.
• Provide the system Kerberos configuration, or point the execution JVM at a configuration file with -Djava.security.krb5.conf=/etc/etlworks/krb5.conf and restart that runtime:

[libdefaults]
    default_realm = EXAMPLE.COM

[realms]
    EXAMPLE.COM = {
        kdc = dc01.example.com
    }

[domain_realm]
    storageaccount.file.core.windows.net = EXAMPLE.COM

• The account must also have share-level authorization and directory/file permissions appropriate to the flow — successful authentication alone does not grant access.
• Use the real server hostname in Host. The service ticket is requested for cifs/<host>, so Azure or AD identity setup must register the correct service principal. Do not use an IP address or an arbitrary alias.
• Do not set a JVM-wide sun.security.krb5.principal — it can override per-connection principal selection. Do not force obsolete Kerberos encryption types.

Credential sources:

Protect keytab and cache files so only the execution service identity and necessary administrators can read them. On Linux, a file cache can be initialized by the same service identity, for example:

kinit -k -t /secure/etlworks.keytab -c /secure/etlworks.ccache user@EXAMPLE.COM
klist -c /secure/etlworks.ccache

Renewal: the connector logs in on each connection and logs out at disconnect. Password and keytab modes obtain fresh credentials on reconnect. Ticket-cache mode attempts TGT renewal where possible but does not maintain the cache in a background service — arrange external renewal or reacquisition for unattended schedules.

Note: Kerberos over the connector's SSH tunnel is not supported, because the tunnel changes the service hostname the ticket is requested for.

Run Test Connection first, then list the target directory and read a small test file. For write flows, also create, read, and delete a disposable file in the intended folder.

Connect to Azure Files

Use the SMB Share connector (not Azure Blob Storage) to work with Azure Files shares. Two authentication options are supported:

Option 1: storage account key (NTLM). Azure Files supports NTLMv2 with a storage account key, but not with an AD/domain user's password.

The Password is the storage account key — not an AD password, SAS token, or application client secret. Keep it in the protected Password field. The Azure account must allow NTLMv2 authentication and storage-account-key access, and must permit SMB 3.0 with AES-128-CCM. The Etlworks execution host must resolve the endpoint and reach TCP 445 and be allowed by the storage account firewall or private endpoint configuration (with a private endpoint, keep the public FQDN and resolve it to the private address in DNS).

Option 2: identity-based authentication (Kerberos). If key-based access is prohibited by policy, configure identity-based authentication on the Azure file share (an AD DS or Microsoft Entra Domain Services deployment with a reachable KDC) and use the Kerberos authentication setup above with Host set to <storage-account>.file.core.windows.net. Enabling Microsoft Entra Kerberos alone does not give a generic Java host password-based Kerberos login — cloud ticket acquisition and managed-identity authentication are not supported.

Connect to an SMB Share over SSH tunnel

An SMB Share that sits behind a firewall cannot be accessed directly from a client on the other side of the firewall, but it can often be accessed through an SSH tunnel. The firewall must be configured to accept SSH Connections, and you also need to have an account on the SSH host for this to work.

Note: Use an actual SMB Share hostname when configuring the Connection. Etlworks will automatically replace it with the localhost and the available port.

Note: The SSH tunnel works with NTLM authentication only. Kerberos authentication is not supported over the SSH tunnel.

If you need to access an SMB Share that can only be accessed via an SSH tunnel, you need to specify additional information in the Connect over SSH tunnel section of the Connection screen.

• SSH Host: the name or IP address for the host accepting SSH Connections.
• SSH Port: the port accepting SSH Connections. The default value is 22.
• SSH User: the user name.
• SSH Password: the optional password.
• Private Key File: the private key file in the pem or ppk Format used for SSH authentication. Click the Upload SSH key to manage SSH keys using GUI. You can also upload the private key file manually and use the token {app.data} as a part of the filename, for example, {app.data}/keys/secret.pem. This parameter is optional.

• SSH Passphrase: the optional passphrase (password) used together with a private key file.

Decryption

When SMB Share Connection is used as a source (FROM) in the source-to-destination transformation, it is possible to configure the automatic decryption of the encrypted source files using the PGP algorithm and private key uploaded to the secure key storage.

If the private key is available, all source files processed by the transformation will be automatically decrypted using the PGP algorithm and given key.  Note that the private key requires a password. 

Read how to generate a pair of public/private keys.

Expected Compression

The Expected Compression setting allows you to specify the compression format expected when reading individual files from a connection. Supported options include No Compression, Zip, and GZip.

If set to Zip or GZip, Etlworks will automatically decompress each resource as it’s read. This setting assumes that each compressed file contains a single resource; it does not support archives with multiple files. Use this setting with caution, as the system will always attempt to decompress the resource based on the selected format, regardless of its file extension or actual content.