SMB External Storage¶

SMB external storage allows connecting Nextcloud to Windows shares or Samba servers. This can be useful for integrating with corporate file servers, sharing large datasets, or user-specific home directories.

This article explains how to set up the SMB external storage app in Nextcloud and how to test it using a Dockerized Samba server.

Prerequisites¶

Running Nextcloud instance with admin access

smbclient and php-smbclient installed on the server

Docker installed (for test environment)

A browser (for admin UI setup)

Enabling and Configuring SMB in Nextcloud¶

Enable the external storage app:

occ app:enable files_external

Enable the External storage support backend:

• Log into Nextcloud as admin
• Go to Apps > Integration
• Enable External storage support if it's not already active

Add an SMB mount via the admin UI:

• Go to Settings > Administration > External storages
• Add a new storage:
  • Storage: SMB/CIFS
• Folder name: e.g., Public Share
• Host: 127.0.0.1
• Share: public
• Username: smb1
• Password: pwd1

Save and ensure you see a green checkmark

Setting up a Local SMB Test Server (Docker)¶

You can test the setup locally using a Dockerized Samba server. The following commands create a test SMB server with a public (shared) directory and per-user home directories:

mkdir -p /tmp/samba/{public,home/{smb1,smb2}} chmod a+rw /tmp/samba/home/smb* docker run -it -p 139:139 -p 445:445 \ -v /tmp/samba/public:/smbpublic \ -v /tmp/samba/home:/smbhome \ dperson/samba \ -u "smb1;pwd1" \ -u "smb2;pwd2" \ -s "public;/smbpublic;yes;no;yes" \ -s "home;/smbhome/%U;yes;no;no;all;none"

Use this for testing only.

Ensure smbclient Is Configured Properly.

Your Nextcloud server should have the SMB client properly configured.

/etc/samba/smb.conf [global] client min protocol = SMB2 client max protocol = SMB3 hide dot files = no

Testing Access¶

Verify from the command line:

smbclient //127.0.0.1/public -U smb1 smbclient //127.0.0.1/home -U smb1 --password=pwd1

Then in Nextcloud, go to Files, and access the configured folder.

Try:

• Uploading a file
• Creating a folder
• Renaming or deleting content

You should see changes reflected on the Samba side.

Troubleshooting¶

If you see a red square or Storage not available:

• Check your SMB credentials
• Ensure the Docker container is running
• Confirm smbclient and php-smbclient are installed
• Restart Apache or PHP if needed:

sudo systemctl restart apache2 # or sudo systemctl restart php-fpm