Apache NiFi with SMB and Windows file shares

Connecting Apache NiFi to SMB and Windows file shares with ListSmb, FetchSmb and PutSmbFile

Teams that move files between a Windows Server or Samba share and other systems often start with a mounted drive and a scheduled copy script. NiFi handles this directly with ListSmb, FetchSmb and PutSmbFile, which list, retrieve and write files over the SMB protocol without a CIFS mount on the NiFi hosts. The trade-off is that a mount makes the share look like a local directory to every process on the host, while the NiFi processors make each transfer an explicit, logged step that runs under a named account with a defined scope. ListSmb writes file metadata as FlowFile attributes or records, and FetchSmb retrieves the content of the files it finds. PutSmbFile writes FlowFile content to a Samba or Windows Server location, and its documentation recommends it over CIFS mounts when share access control matters.

ListSmb is designed to run on the primary node only, so a cluster does not pick up the same file twice. When the primary node changes, the new primary continues from the state the previous one stored, which makes the listing step predictable but also means the listing throughput is bounded by one node. Plan the schedule with that in mind, and confirm in the ListSmb documentation how the listing state is kept across restarts before you rely on it for exactly-once handling. Downstream FetchSmb and PutSmbFile steps can run on any node. Decide early whether files are removed or moved after successful retrieval, because that choice belongs to the share owner as much as to the flow designer.

Credentials and folder structure need the same care. The account NiFi uses should have only the read or write rights the flow needs on the specific folders involved, and the password should be held in a parameter or sensitive value rather than in the flow definition. Confirm with your Windows Server or Samba administrator how the share's permissions, SMB protocol version and any signing requirements apply to a service account, since those settings decide whether the processors can connect at all. Agree on a folder layout for inbound, processing and completed files before the first run. A flow that writes into the wrong folder is much harder to unwind than one that stops on a permission error.

What the SMB integration needs before the first flow runs

Before ListSmb or PutSmbFile can touch a share, the NiFi runtime, the file server, the service account and the network path all need to agree. Each card below is a prerequisite that is easy to assume and expensive to discover in production.

NiFi 2 on Java 21

Run NiFi 2 with the Java 21 runtime, which the NiFi administration guide lists as the minimum. Confirm the exact NiFi 2 release you intend to deploy, since the downloads page lists the current release and the migration path from 1.x runs through NiFi 1.27.0 first. Check the processor documentation for the build you deploy, because the SMB processors and their properties can differ between releases.

Share server and its details

Record whether the target is a Windows Server file share or a Samba share, along with the host name, share name and folder layout. If Samba is the server, confirm whether it is a domain member or an Active Directory domain controller, since the Samba wiki advises against using a domain controller as a file server when multiple DCs exist. Ask the server owner which SMB protocol version is enforced, and confirm it against the ListSmb and PutSmbFile documentation.

Service account and share permissions

Create a dedicated service account for NiFi with the least rights needed to read the source folder and write to the delivery folder. Grant share-level and NTFS or file-system permissions separately, and confirm that the account can rename or move files if your pickup pattern depends on it. Document who owns the account, its password rotation process and where the credential will be stored in NiFi.

Network reachability on SMB

Confirm that every NiFi node, not only the primary, can reach the file server on the SMB port and resolve its name through DNS. Firewalls between the NiFi network segment and the file server are a common cause of failed listings that look like credential errors. Test from each node with the same account the processors will use, and record the results before the first flow is scheduled.

Cluster state for primary node listing

ListSmb is designed to run on the primary node only, so the NiFi cluster must have working coordination and state for a new primary to resume from the last listing. Confirm that the cluster uses ZooKeeper, embedded or external, or Kubernetes ConfigMaps or Leases, as described in the administration guide. Without healthy cluster state, a failover can cause repeated or missed pickups.

Folder structure and processor properties

Agree on the folder layout for incoming, processed and failed files before building the flow, since listing and delivery paths depend on it. Decide how processed files will be moved or archived so they are not picked up twice. Confirm each ListSmb and PutSmbFile property name, default and required setting against the component documentation for your NiFi build, then test with a small sample folder.

How to configure ListSmb, FetchSmb and PutSmbFile in sequence

This sequence takes a NiFi cluster from an empty canvas to a verified pickup and delivery path on an SMB share, with each step confirmed before the next one starts. The output is a listing on the primary node, fetched files flowing through the flow, and a test file written to the target folder.

Prepare the share account and folder layout
Your Windows or Samba administrator creates a dedicated service account with the least access needed, grants read rights on the pickup folder and write rights on the delivery folder, and agrees on the folder names with the flow owner. Confirm the account with a manual login from a NiFi node host using the same share name and credentials the flow will use. Done means the account can list and read the pickup folder and can create a test file in the delivery folder, and nothing outside those two paths is reachable.
Create the SMB credential configuration
In NiFi, add the SMB connection service that your version of the component documentation names for ListSmb, FetchSmb and PutSmbFile, and enter the host, share, domain and service account. Store the password as a sensitive value rather than in plain flow text, and reference the same service from all three processors so credentials change in one place. Done means the service shows as enabled and the validation status is clean on a processor that uses it.
Set the share path and confirm the connection
Point the service at the share and the subfolder that holds the source files, using the path format the component documentation shows for your NiFi 2 release. Run a short test from the configured service or a processor in a stopped state to confirm the network route, name resolution and authentication from every node that could host the primary role. Done means each node reports the same successful connection, and any failure is traced to DNS, firewall or permission settings before you go further.
Configure ListSmb on the primary node
Add ListSmb, select the shared connection service, and set the folder path and file filters to match the pickup folder. Keep the processor scheduled so it runs on the primary node only, which lets a new primary resume from stored state after a failover. Choose the metadata output mode your downstream logic needs, either attributes or records, and keep the run schedule modest until the listing is understood. Done means the processor shows FlowFiles for the expected files on the primary node, with path and name attributes present, and a second run does not re-list files already seen.
Add FetchSmb to retrieve listed files
Connect the ListSmb success relationship to FetchSmb and set FetchSmb to read the remote file named by the attributes ListSmb wrote, using the same shared service. Route success to the next stage and send failures to a retry or error path rather than dropping them. Test with one or two files first, then confirm the FlowFile content matches the source byte count and checksum. Done means the content is present in the flow, the original file is still on the share, and failed fetches are visible in the error route.
Configure PutSmbFile for delivery
Add PutSmbFile, select the same connection service or a separate one scoped to the delivery share, and set the target folder and the conflict behavior your process requires. The component documentation recommends PutSmbFile over CIFS mounts when share access control matters, so keep the delivery account separate from the pickup account if your policy requires it. Done means a test FlowFile lands in the delivery folder with the expected name and size, and the write is rejected cleanly when the account lacks permission.
Verify the end-to-end path and record the result
Drop a known test file into the pickup folder, let the flow run through listing, fetching and delivery, and compare source, FlowFile content and target file. Then stop the primary node in a test cluster or change primary assignment, and confirm listing resumes on the new primary without duplicates. Save the verification output, the account and folder permissions used, and the processor settings in your change record. Done means the sequence works from a clean start and the evidence is filed for your operations team.

Choosing between a Windows Server share and a Samba share

A Windows Server file share is usually part of an Active Directory domain where the Windows team already manages users, groups and NTFS permissions. Share permissions and NTFS permissions are set through the same management tools the team uses for other servers, and audit policy is usually already in place. For NiFi, this means the service account that ListSmb, FetchSmb and PutSmbFile use is an ordinary domain identity whose rights are granted by the Windows administrators.

Permission ownership: Windows administrators typically control both share and NTFS rights, so the NiFi service account's access is a Windows change request.
Existing controls: Group policy, auditing and backup for the file server may already cover the folders NiFi reads from.
Clustering: Confirm the server version and SMB protocol settings your NiFi processors will negotiate, since these depend on your own environment.
Operational fit: Teams that already run Windows file services often prefer keeping the share where it is rather than moving it.
Licensing and support: Confirm the licensing and support terms for your server edition with the vendor, as these are outside this page.

Before you build, check which team approves changes to the NiFi service account's share and folder permissions and how those changes are logged.

When Samba runs as an AD DC, domain objects, users, groups and functional levels are administered with the samba-tool command rather than the Windows management consoles. That changes the skill set and the change path: a team that only knows Windows administration may not be able to adjust a NiFi service account without help from the Samba owners. The split between directory administration and file serving should be decided before the NiFi account is created.

Command-line administration: Users, groups and functional levels are managed with samba-tool, so changes should be scripted and reviewed.
Separate file server: Keeping file serving on a domain member lets the file team manage shares without giving them directory administrator rights.
Functional level changes: Raising levels is a domain-wide change that should be planned and tested outside the file team's scope.
DNS backend choice: Samba AD DC supports SAMBA_INTERNAL and BIND9_DLZ backends, and the wiki warns against NONE and does not support BIND9_FLATFILE.
Ownership record: Write down who approves the NiFi account, the share ACLs and the directory changes.

Ask your identity team which group can change NiFi's service account and its share permissions, and confirm that the answer matches your audit and change-control process.

Designing folder structures and state so pickups are not duplicated

Duplicate pickups are usually a folder design problem before they are a NiFi problem. ListSmb records what it has already listed as state, and that state is what keeps a file from being picked up twice. Give each flow its own inbound folder that only the producing system writes to, and a separate processed or archive location that NiFi writes to after delivery succeeds. Avoid having NiFi move files within the folder it is listing, since renames and moves change the metadata ListSmb sees and can produce a second pickup under a new name. Agree a naming convention with the source team before go-live, such as a timestamp prefix plus a source identifier, and confirm whether the producing application ever overwrites a file under the same name. An overwrite is the most common cause of a file that appears to be new but is really a re-send.

ListSmb is designed to run on the primary node only, and the NiFi documentation says a new primary node picks up where the previous one left off. Confirm that this handoff works in your cluster by checking that the state the processor keeps is stored in cluster state, not on a single node's local disk, and that the processor is scheduled on the primary node in your flow. Test the handoff deliberately: drop a known set of files, let the listing run, then stop the primary node during a listing cycle and confirm that the new primary lists the remaining files exactly once. Repeat the test with a file that changes size while the listing is in progress, because a partially written file is a more likely source of duplicates than a clean failover. Record the results, the file names and the state contents, so the team can repeat the test after each NiFi upgrade.

Mapping SMB file metadata and share paths to NiFi attributes and records

This table compares how SMB listing metadata and share paths move between ListSmb, FetchSmb and PutSmbFile in attribute mode and record mode. Use it to decide which fields your routing logic needs and where the output path is built. The main takeaway is that the attribute names and record schema depend on the ListSmb output mode, so confirm them in the component documentation before you write routing rules.

Item	Attribute mode	Record mode	What to confirm
File name and folder path	Stored as FlowFile attributes for each listed file	Stored as fields in each record of the listing output	Exact attribute or field names in the ListSmb documentation
File size	Available for routing on size thresholds	Available as a numeric field for record path filters	Field type and units for your Samba or Windows Server version
Timestamps	Used to order or filter files by modification time	Used in record-based filters and time windows	Which timestamp fields are emitted and their time zone
Share-relative path	Needed to rebuild the source path before FetchSmb	Needed in the record that drives FetchSmb per file	Whether the path includes the share name or starts below it
Target path for PutSmbFile	Built with Expression Language from attributes and the target share	Built from record fields with a record path expression	How trailing separators and nested folders are created on the target
Routing on metadata	Route on attributes with RouteOnAttribute	Route on fields with record-based routing processors	Whether your flow needs a schema change when the listing format changes
Primary node behavior	Listing state keeps the metadata consistent after a primary node change	Same state behavior applies to record output	State handling for your cluster during a primary node failover

Securing share access, credentials and the NiFi side of the connection

A NiFi flow that reads and writes a Windows or Samba share inherits two sets of permissions: the share's and NiFi's. The cards below cover the share account, where secrets live, who can change the flow and how operators sign in, so each side is locked down on purpose.

Least-privilege share service account

Create a dedicated domain or local account for NiFi and grant it only the share, folder and NTFS or Samba permissions the flow needs. Use read-only rights for ListSmb and FetchSmb sources and write rights only on the delivery folder for PutSmbFile. Confirm with your Windows or Samba administrator how the account's password rotation and lockout policy will be handled, because a locked service account stops every flow that uses it.

Credentials in sensitive properties

Enter the share password into a sensitive property on the controller service or processor, or reference it from a sensitive parameter in a parameter context. Keep the value out of flow definitions committed to Git, and check that the parameter context does not expose it to users who only need to view flows. Ask who holds the encryption key for the sensitive properties and how it is backed up.

Restricting who can change the flow

Use NiFi's authorization policies to separate users who view the canvas, users who operate processors and users who change the flow or read sensitive values. Limit the policies that expose parameter values and controller service details to a small operator group. Review these policies after each staff change, since a user who can edit a processor can also point it at a different share.

Operator sign-in with LDAP, OIDC or SAML

Give operators individual accounts through an external provider: LDAP, OpenID Connect, SAML 2.0 or X.509 client certificates. Avoid sharing the single-user account, which exists for simple setups. The Kerberos provider is deprecated for NiFi access, so do not plan new work around it even if your directory is Active Directory. Confirm with your identity team which provider they will support and how group membership maps to NiFi policies.

Choosing PutSmbFile over CIFS mounts

Writing through a CIFS mount in the operating system hides the share's access control from NiFi, so every flow runs with whatever mount account the host holds. PutSmbFile authenticates to the share directly, which keeps the permission model visible and per-flow. Where share access control matters to your auditors, prefer this processor and document why the mount approach was rejected.

Why SMB listings, fetches and writes fail in NiFi

This table lists the failures teams most often hit when ListSmb, FetchSmb and PutSmbFile run against Windows Server or Samba shares, with the likely cause and the first fix for each. Use it as a triage checklist, then confirm version-specific behavior in the ListSmb and PutSmbFile component documentation before changing a production flow.

Symptom	Likely cause	Fix to try first
Duplicate pickups after a primary node change	ListSmb state is tied to the primary node, and a handover can re-list files that were already processed if state did not carry over cleanly.	Confirm the listing state behavior in the ListSmb documentation for your version, then add a downstream duplicate check on file name, size and modified time.
Access denied on listing or fetch	The service account lacks read or list permission on the share or on the NTFS folder beneath it, or the share and NTFS permissions conflict.	Check both share-level and NTFS permissions for the account, and test with the same account from a Windows host before changing NiFi.
Authentication fails or credentials are rejected	Password expired, wrong domain or realm in the username, or a local account used where a domain account is required.	Use the domain-qualified username in the controller service, confirm the password is current, and check the account is not locked or forced to change.
Connection drops or protocol negotiation fails	The server requires a newer SMB dialect or signing setting than the client offers, or the reverse, after a server or Samba upgrade.	Compare the SMB version and signing requirements on the server with the client settings, and adjust them in a test environment first.
Target folder not found on write	PutSmbFile does not create every missing parent path in the way the operator expects, or the path uses the wrong separator or case.	Create the destination folder structure in advance, use forward or back slashes consistently as the component documents, and match share-relative paths exactly.
Write or read fails on a locked file	A Windows application such as an office suite, backup agent or antivirus scanner holds an exclusive lock on the file.	Pick up files only after a settle period, write to a temporary name and rename on completion, and route locked-file failures to retry instead of error.
Listings run on every node and files are picked up twice	The ListSmb processor was scheduled without primary node only execution, so each cluster node lists the share.	Set the processor to run on the primary node only, and confirm the scheduling setting in the component documentation for your NiFi version.
Share works from a Windows client but not from NiFi	NiFi hosts are not resolving the server name, a firewall blocks SMB traffic from cluster nodes, or only one node can reach the share.	Test name resolution and port reachability from every node, not only the one that serves the UI.

Questions buyers ask before outsourcing SMB file integration

What drives the cost of an SMB file integration project?

The cost depends mostly on how many shares are involved, how deep and irregular their folder structures are, how many files move each day, and how much Active Directory work sits around the flows. A single share with one flat folder and a known file volume is a small scope. Ten shares with nested departmental folders, mixed permissions and files that must be checked before delivery is a larger one. Costs are one-time for design, build and testing, and recurring only if you buy ongoing support or retainer work. Ask any provider for a quote that lists each share, each flow, each credential and each environment (test and production) as separate line items.

How long does an SMB file integration take to deliver?

The duration depends more on environment readiness than on NiFi itself. The flows are usually a modest part of the work. The longer tasks are getting share access approved, creating service accounts, agreeing folder conventions with the file owners, and scheduling change windows for production. If those inputs arrive late, the build waits. Ask for a timeline that names the client inputs and the date each one is needed, and treat any duration that does not list its dependencies with suspicion. No duration is given here because none is supported by the researched material for this topic.

What do we need to provide before the work starts?

Most delays trace back to a short list of client inputs:

Access to the target shares, with the share names, host names and the permissions that the integration needs
A dedicated service account for each direction (listing, fetching and writing), with its password handled through your secrets process
Representative test data, including file names, sizes, encodings and a sample of nested folders
Named owners for each share who can confirm folder structures and retention rules
Change windows for production cutover and a rollback plan you approve

Can our own team build SMB integration in NiFi without a partner?

Yes, a team with NiFi experience and Windows or Samba administration skills can build it alone. The processors are documented on the Apache NiFi component pages, and the work is mostly configuration, state handling and testing. The skills that are often missing are how the share permissions are set, how the service account is scoped, and how the flow behaves when a new primary node takes over. A partner is worth comparing when those skills are thin, when several shares must be migrated at once, or when your team cannot take on the testing and documentation load. Ask for a written scope either way so you can compare the two options on the same basis.

Does the project include Samba, or only Windows Server shares?

Whether Samba is in scope depends on what you run. ListSmb, FetchSmb and PutSmbFile work against shares on Samba or Windows Server, so the NiFi side is the same in both cases. If your file server is Samba, the Samba configuration, its authentication and its share permissions are a separate piece of work and should be named in the scope. If Samba acts as an Active Directory domain controller, the Samba wiki advises against also using that controller as a file server when multiple domain controllers exist, and recommends a separate domain member for file serving. Confirm which of these applies before you ask for a quote.

How does Active Directory integration affect the effort?

Active Directory affects the work in two places: the service accounts and group memberships that the flows use, and the permissions on the shares. If your directory is clean and the groups already match the folder structure, the work is limited to creating the accounts and checking access. If groups are inconsistent, nested or managed by another team, the effort rises because each change needs approval. Samba can run as an Active Directory domain controller, and the Samba wiki documents the functional levels and the samba-tool commands used to manage them. Ask whether the provider will review group design before building flows.

What should we check about credentials and share access before we approve a scope?

Check whether each flow uses its own least-privileged account, whether passwords are stored in a credential mechanism rather than in flow files, and whether the account can read only the folders it needs. Also confirm who approves changes to share permissions and how that approval is recorded. Ask the provider to show how credentials are supplied to the NiFi processors and how access is tested in the test environment before production. Any statement that the integration is secure should be backed by a documented access model that your security team has reviewed.

How DeployOpen scopes and delivers the SMB file integration

DeployOpen plans, builds, documents and supports Apache NiFi flows that pick up and deliver files on Windows Server and Samba shares inside infrastructure you control. Each engagement starts from a written scope that fixes the share paths, access model, credentials approach and handover deliverables before any flow is built.

How we scope

Inventory every share, folder and file pattern the flows will read from or write to, with the owning team named for each.
Confirm which NiFi cluster nodes will run ListSmb on the primary node and how a primary node change will be tested.
Agree the service account model, share permissions and credential storage method in writing before any flow is built.
Record the expected folder structure, file naming rules and archive or delete behavior as part of the fixed scope.

How we build

Build ListSmb, FetchSmb and PutSmbFile flows with controller services that hold share credentials outside the flow definition.
Configure a separate Samba domain member or Windows file server for file serving rather than using a domain controller as the file server.
Test pickup and delivery against copies of production share structures, including duplicate, partial and locked file cases.
Version flows in a Git-backed registry where your environment supports it and document each flow change in a change record.

How we hand over

Deliver a runbook covering share paths, service accounts, credential rotation steps and the expected folder layout for each flow.
Document primary node behavior, restart tests and what operators should check after a failover or node replacement.
Walk your operations and security teams through permission reviews and the access evidence they can retain for audit.
Provide a list of open items, assumptions and the configuration values your team must confirm in its own environment.

How we support

Engagements are fixed-scope, and ongoing support, upgrades and continuous testing are available as a retainer.
Review NiFi, Samba and Windows share configuration changes when your team plans upgrades or directory changes.
Re-run file integrity and access tests after patches, share migrations or changes to the service account model.
Confirm the supported Samba and NiFi versions for your environment with the vendor before each planned upgrade window.