Skip to content

Filesystem Connector - Docker Deployment🔗

The Filesystem connector scans files from a directory on the Docker host.

Docker Compose relies on the host operating system’s filesystem, so any storage that the host can mount (for example NFS, SMB/CIFS, or other network filesystems) can be scanned by bind-mounting the path into the container.

Kubernetes alternative

The Kubernetes deployment of the Filesystem connector can serve as a very versatile alternative when scanning volumes backed by Kubernetes StorageClass resources.

This allows scanning of storage types such as NFS, CephFS, AWS EFS, Azure Files, Longhorn RWX volumes, and other CSI-backed storage systems.

See Filesystem Connector — Kubernetes Deployment for more information.

In the official Docker Compose bundles:

  • DSXCONNECTOR_ASSET defines the host path to scan.
  • Docker Compose bind-mounts that path into the container at /app/scan_folder.
  • The connector scans /app/scan_folder internally.

Unlike cloud/API connectors (S3, GCS, SharePoint, etc...), the Filesystem connector requires bind-mounted storage. See Storage Binding for more information.

Prerequisites🔗

The Filesystem connector requires access to the directory being scanned.

Ensure the Docker host can access the filesystem path you intend to scan. Network storage (NFS, SMB, etc.) must be mounted on the host before starting the connector.

Minimal Deployment🔗

The following steps will install the connector with minimal configuration changes. Read the following section for specific configuration details.

Using the Docker bundle

All Docker connector deployments use the official DSX-Connect Docker bundle, which contains the compose files and sample environment files for each connector.

DSX-Connect Docker bundles

Download the DSX-Connect Docker bundle and navigate to the Filesystem connector directory: dsx-connect-<core_version>/filesystem-connector-<connector_version>/

The easiest way to deploy the Filesystem connector is by editing the supplied sample.filesystem.env file and using it with the supplied docker-compose-filesystem-connector.yaml compose file.

Set scan and quarantine paths🔗

In this example, we will scan /mnt/DESKTOP1/share and quarantine files in /var/lib/dsxconnect/quarantine-DESKTOP1. These are directories that already exist on the Docker's host filesystem. 

# sample.filesystem.env
DSXCONNECTOR_ASSET=/mnt/DESKTOP1/share
DSXCONNECTOR_ITEM_ACTION=move
DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO=/var/lib/dsxconnect/quarantine-DESKTOP1

Deploy🔗

docker compose --env-file sample.filesystem.env -f docker-compose-filesystem-connector.yaml up -d
That’s it. You should now be able to see the connector in the DSX-Connect UI.

The compose bundle will:

  • Bind ${DSXCONNECTOR_ASSET} → /app/scan_folder <-- internal to the filesystem connector container
  • Bind ${DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO} → /app/quarantine <-- internal to the filesystem connector container

How the Compose Bundle Works🔗

Excerpt from the official compose pattern:

volumes:
  - type: bind
    source: ${DSXCONNECTOR_ASSET:-/tmp/dsxconnect-scan}
    target: /app/scan_folder
  - type: bind
    source: ${DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO:-/tmp/dsxconnect-quarantine}
    target: /app/quarantine

environment:
  DSXCONNECTOR_ASSET: ${DSXCONNECTOR_ASSET:-/tmp/dsxconnect-scan}
  DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO: ${DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO:-/tmp/dsxconnect-quarantine}

Important:

  • DSXCONNECTOR_ASSET is a host path
  • The container always scans /app/scan_folder
  • You typically do not change the container paths

Required Settings🔗

DSXCONNECTOR_ASSET

Defines the host directory to scan.

Example:

DSXCONNECTOR_ASSET=/mnt/DESKTOP1/share

This host directory will be mounted into the container at:

/app/scan_folder

DSXCONNECTOR_ITEM_ACTION

Defines what happens to malicious files.

Common values:

  • nothing (report only)
  • move (quarantine)
  • delete

If using move, also set:

DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO

Defines the directory to move quarantined files to. 

DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO=/var/lib/dsxconnect/quarantine-DESKTOP1

Monitoring🔗

The Filesystem connector uses the Python watchfiles library for file change detection.

Depending on how your filesystem is mounted, you may be able to use native OS file events — or you may need to force polling mode.

✅ When DSXCONNECTOR_MONITOR=true Is Enough🔗

Use the default setting:

DSXCONNECTOR_MONITOR=true

This works without forcing polling when the connector has access to:

  • Native Linux filesystems (ext4, xfs, etc.)
  • Local macOS filesystem (running directly on macOS)
  • Colima (when using virtiofs)
  • WSL2 with local filesystem
  • Docker on Linux host with bind-mounted local paths

In these environments, watchfiles can use native OS event APIs:

  • Linux → inotify
  • macOS → FSEvents
  • Windows → ReadDirectoryChangesW

These event systems are efficient and real-time.

⚠️ When You Must Force Polling🔗

Enable polling mode when filesystem events may not propagate correctly into containers:

DSXCONNECTOR_MONITOR=true
DSXCONNECTOR_MONITOR_FORCE_POLLING=true
DSXCONNECTOR_MONITOR_POLL_INTERVAL_MS=1000

Polling mode is recommended for:

  • Docker Desktop (macOS / Windows)
  • SMB / CIFS shares
  • NFS mounts
  • Kubernetes Persistent Volumes backed by NFS
  • Remote or network filesystems
  • Any scenario where file changes are not being detected reliably

In these environments, native file system events often do not cross VM or network boundaries, so watchfiles must periodically scan for changes.

🧠 Practical Rule of Thumb🔗

If the connector runs:

  • On the same machine as the files → DSXCONNECTOR_MONITOR=true is usually fine
  • Across a VM boundary, container boundary, or network mount → enable polling

🔍 Troubleshooting Tip🔗

If files are not being detected:

  1. Enable debug logging.
  2. Temporarily force polling.
  3. If polling fixes it → your filesystem does not propagate native events.

Multiple Connector Instances (Advanced)🔗

.env is ideal for a single connector instance.

If you need to scan multiple directories (for example, multiple desktops or storage mounts), you should:

  1. Copy the filesystem_connector service block in the compose file.
  2. Rename the service (e.g., filesystem_connector_desktop1, filesystem_connector_desktop2).

  3. Update:

    • ports
    • DSXCONNECTOR_ASSET
    • DSXCONNECTOR_ITEM_ACTION_MOVE_METAINFO
    • DSXCONNECTOR_CONNECTOR_URL
    • Optional display name

Example:

filesystem_connector_desktop1:
  ports:
    - "8620:8620"
  volumes:
    - type: bind
      source: /mnt/DESKTOP1/share
      target: /app/scan_folder

Multi-instance deployments require editing the compose YAML. .env files alone simply become unmanagable for multiple services in the same project.

Storage Mounts (NFS / SMB / Remote Shares)🔗

For instructions on mounting remote storage on the Docker host, see:

Storage and Mounts

Remote shares must be mounted on the host first, then bind-mounted into the container.

If DSX-Connect Core is using TLS, set DSXCONNECTOR_DSX_CONNECT_URL protocol to https:

DSXCONNECTOR_DSX_CONNECT_URL=https://dsx-connect-api:8586