How to Set Up SMB External Storage in Nextcloud

SMB (Server Message Block) external storage lets you mount Windows shares, Samba servers, and NAS devices directly into Nextcloud. Instead of copying files into your Nextcloud server, you access them on-demand from their original location. This keeps data centralized on your existing infrastructure while giving every Nextcloud user instant access through a unified interface.

What is SMB/CIFS External Storage in Nextcloud?

SMB (Server Message Block) and CIFS (Common Internet File System) are Windows file-sharing protocols. In Nextcloud, they let you mount remote shares as folders inside your Nextcloud interface. Users see them like any other Nextcloud folder, but the files sit on your NAS, Windows Server, or Samba server.

Why not just store files in Nextcloud? Cost and control. A 2TB NAS with SMB costs far less than doubling your Nextcloud server disk. You keep backup and compliance workflows on the share itself. Nextcloud becomes the access layer, not the storage layer.

Example: Your company uses a Synology NAS for team data. You mount its SMB shares into Nextcloud. Users access files through Nextcloud's web interface and mobile apps, with Nextcloud's version history and activity logs on top. The original data stays on the NAS, unchanged. This is common in enterprises migrating from shared drives or Samba to a modern file portal. SMB is mature, stable, and ubiquitous in Windows and Linux environments.

Prerequisites: What You Need Before Configuration

Before you configure SMB mounts, your Nextcloud server needs three things: the system package, the PHP extension, and network access to the SMB endpoint.

System packages: Your server must have smbclient installed. On Ubuntu/Debian, run:

sudo apt-get install smbclient

On CentOS/RHEL:

sudo yum install samba-client

PHP extension: Nextcloud requires the php-smbclient PECL extension. This is different from the system smbclient package. If you are running a stock Nextcloud installation (not containerized), your hoster may have pre-installed it. If not, or if you manage your own server, install it:

sudo pecl install smbclient
echo "extension=smbclient.so" | sudo tee /etc/php/YOUR_VERSION/mods-available/smbclient.ini
sudo phpenmod smbclient
sudo systemctl restart php-fpm

Replace php-fpm with apache2 if you are using Apache.

Nextcloud version: SMB support requires Nextcloud 13 or later. Current versions (26+) include it by default.

Network access: Your Nextcloud server must be able to reach the SMB host on port 445 (or custom SMB port). If your SMB server is behind a firewall or on a private network, you must ensure the Nextcloud server has a route to it. For managed Nextcloud hosting on Opsily, this often means adding your SMB endpoint to an allowlist or running the Nextcloud instance and SMB share on the same VPC.

Verify everything works: Test SMB connectivity from the Nextcloud server:

smbclient -L //SHARE_HOST -U USERNAME

Check that php-smbclient is loaded:

php -r "phpinfo();" | grep smbclient

If both succeed, you are ready to configure.

How to Enable the External Storage App

Nextcloud includes the External Storage Support app, but it is disabled by default. Enable it in the admin panel.

Log in as an admin user.
Click the user menu (top right) and select "Administration."
In the left sidebar, go to "Apps."
Click "Disabled apps" to filter the view.
Search for "External storage support."
Click "Enable."

After enabling, you will see a new "External storages" option under "Administration" > "Storage." This is where you configure SMB mounts.

Step-by-Step: Configure SMB/CIFS Mount

Once the External Storage app is enabled, adding an SMB mount takes about five minutes.

1. Go to Admin > External storages.

In the admin panel, under "External storages," you will see a form to add a new storage.

2. Fill in the Folder name.

This is the name users see in Nextcloud (e.g., "Team Files" or "Company NAS"). Use something descriptive.

3. Select SMB/CIFS from the dropdown.

In the "Storage" dropdown, pick "SMB / CIFS."

4. Enter the SMB server details:

Host: The IP address or hostname of your SMB server (e.g., 192.168.1.10 or nas.example.com).
Username and Password: Credentials with read/write access to the share. Leave blank if the share allows anonymous access (rare).
Share: The exact share name (e.g., TeamData). Do not include backslashes or path prefixes.
Domain (optional): If your SMB server is part of an Active Directory domain, enter it here (e.g., CORP). This is important for AD-authenticated shares.

5. Configure credentials type.

You have four options:

Session credentials (default): Each user enters their own credentials when accessing the mount. Useful if each user has a unique SMB login.
Global credentials: All users access the share with the same credentials you enter here. Simplest if all users have the same access.
Username only: Users enter only their username; Nextcloud uses a global password.
Login credentials: Uses the Nextcloud user's own login (if LDAP or Active Directory is integrated).

For most small-to-medium setups, choose "Global credentials."

6. Assign users and groups.

By default, the mount is available to all users. To restrict it, click "Add group" or "Add user" to limit access. This is a Nextcloud layer; SMB permissions are checked separately (more on that below).

7. Click the checkmark or press Enter.

Nextcloud will test the connection. If successful, a green checkmark appears. If it fails, you will see a red X and an error message.

That is it. Users will now see the mounted share in their Nextcloud file list.

Permissions: How Nextcloud and SMB Permissions Stack

This is where many setups go wrong. Nextcloud permissions and SMB share permissions are two separate layers, and both must allow access.

The SMB layer: The share itself has read/write/execute permissions. These are set on the NAS or Samba server. For example, a Synology share might allow only the "Finance" group to access a folder.

The Nextcloud layer: When you configure an SMB mount, you can restrict it to specific Nextcloud users or groups. Nextcloud enforces its own access control on top of SMB permissions.

How they interact: A user accessing the mount must pass both checks. If SMB denies access but Nextcloud allows it, user sees a "Permission denied" error. If Nextcloud denies access but SMB allows it, user never reaches the share and does not see it in the file list.

Common mistake: An admin sets overly permissive SMB (everyone can read/write) and tight Nextcloud access (only the Finance group). Users outside Finance still cannot access it because Nextcloud blocks them first. Conversely, if SMB is locked down but Nextcloud is wide open, users will see the mount but cannot do anything with it.

Best practice: Align your SMB and Nextcloud permissions. Do not over-restrict one and over-open the other. If a group needs access, allow it at both layers.

Important: SMB permissions include share-level (can you access the share at all?) and file-level (NTFS ACLs on Windows, POSIX on Linux). Nextcloud cannot override file-level permissions. If a Nextcloud user can access the share but a specific folder inside it denies them (via NTFS ACLs), they will hit an error when trying to access that folder.

Common Configuration Failures and How to Fix Them

"Red X" or no green checkmark on the mount

The connection test failed. Diagnose in order:

Check the error message shown on the admin page. It usually says "Connection refused," "Connection timeout," or "Invalid username/password."
From the Nextcloud server, manually test the connection:

smbclient -L //HOST -U USERNAME%PASSWORD

If this fails, the issue is not Nextcloud; it is network or credentials.

Verify php-smbclient is installed and loaded (see Prerequisites section).
Check that the SMB host is reachable from the Nextcloud server. If your Nextcloud is on a separate VPC or data center, you may need a VPN or firewall rule.
Verify the share name is exact. SMB is case-sensitive on some systems.

"Connection timeout"

The Nextcloud server can reach the host on port 445 but is not getting a response.

Check that SMB is actually running on the host.
Verify the port. Some setups use port 139 instead of 445. Try changing the host to //HOST:139.
Confirm your firewall rules. If Nextcloud is on a cloud VPC, ensure outbound traffic to port 445 is allowed.
If the SMB server is behind NAT, ensure port forwarding is configured correctly.

"Permission denied" after successful connection

The connection works but users cannot read/write files.

Check the SMB credentials you entered. The user may not have read/write access to the share.
Check NTFS/POSIX permissions on the share itself.
Verify the Nextcloud user has access to the mount (check the "Restrict to groups" setting).
If using domain credentials, ensure the domain is correctly entered and the user is a member of the group with access.

"Share not found"

The host is reachable but the share does not exist.

List available shares on the host:

smbclient -L //HOST -U USERNAME

Compare the exact share name in the list to what you entered in Nextcloud. One typo breaks it.
Verify the share is exported/shared. On Samba, check /etc/samba/smb.conf. On Synology/Qnap, check the NAS web interface.

Files are not appearing / "occ files:scan" shows no files

The mount is green, but users see an empty folder.

Run a file scan to index the share contents:

sudo -u www-data php occ files:scan --all

Replace www-data with your Nextcloud user if different.

File scanning can take time on large shares. Check the Nextcloud logs for errors:

tail -f /var/www/nextcloud/data/nextcloud.log

If the share is very large (100K+ files), Nextcloud may time out during the initial scan. Consider scanning only the mounted folder:

sudo -u www-data php occ files:scan USERNAME

Performance Considerations: Native SMB vs. OS-Level Mounting

Nextcloud talks to SMB in two ways. Understanding the trade-off helps you choose.

Native SMB driver (Nextcloud's default):

Nextcloud uses php-smbclient to connect directly to the share.
Pros: Simple, no host-level setup, can be added/removed on-the-fly in the admin panel.
Cons: Higher CPU overhead (each file operation is a network call), file scans are slow on large shares, potential metadata caching issues.

OS-level mounting (fstab):

You mount the SMB share on the host's filesystem (like a local disk), then point Nextcloud to that mount as a "Local" storage.
Pros: Faster (OS caching), more stable, standard Linux filesystem semantics apply.
Cons: Requires host-level access, shares are static (cannot be added per user), requires autofs or permanent mounts, more complex to manage.

When to use native SMB:

Small to medium shares (less than 50K files).
You want per-user authentication (each user enters their own SMB credentials).
You prefer simplicity (no host-level setup).

When to use OS-level mounting:

Large shares (more than 100K files) where metadata caching matters.
You need maximum performance and stability (on-premises setups).
All users access the share with the same credentials.

Community reports and Reddit discussions suggest OS-level mounting is more stable for production large-scale deployments. However, if your share is under 100K files and you have a stable network, native SMB is fine and requires less maintenance.

Why Managed Hosting (Opsily) Simplifies SMB Setup

If you run Nextcloud on managed hosting, SMB setup is easier when your provider handles the infrastructure.

Opsily manages the prerequisites for you. PHP-smbclient, smbclient, and all system packages are pre-installed. You do not patch or troubleshoot dependencies.

VPC and network isolation: If your SMB server is on-premises or on a private network, Opsily's managed hosting can establish a VPN tunnel to make it reachable from the Nextcloud instance. No firewall rules to hunt down; Opsily handles it.

Automatic file scans and backups: Opsily's managed service runs periodic file scans on all external storage mounts. Your SMB files are included in automated backups, not just the Nextcloud database.

Storage scaling: You can grow your NAS independently of your Nextcloud server. Opsily keeps Nextcloud optimized while your SMB share grows.

To set up SMB on Opsily: provision your Nextcloud instance on their platform, enable the External Storage app, configure your SMB mount (using the steps above), and ensure your SMB endpoint is reachable via their VPC or VPN. Opsily's support team can help if you run into network connectivity issues. Check Nextcloud plans and pricing to see managed hosting options.

Frequently Asked Questions

Q: Can I mount multiple SMB external storage shares in one Nextcloud instance?

A: Yes. Each share becomes a separate folder in Nextcloud. Add as many as you need in the External Storage admin panel.

Q: What if I have an Active Directory user? How do I use my AD credentials?

A: Enter your domain in the "Domain" field (e.g., CORP.LOCAL) and your AD username and password. Nextcloud will authenticate against the domain. If Nextcloud is LDAP-integrated, choose "Login credentials" auth type and users can use their LDAP login automatically.

Q: Does Nextcloud sync SMB files to its local storage?

A: No. SMB files are accessed on-demand from the share. They are not copied into Nextcloud's database or data folder. This keeps Nextcloud lean and your source data single.

Q: Can I set different access for different users on the same SMB share?

A: Yes, via the "Restrict to groups" or "Restrict to users" setting in the External Storage panel. Nextcloud restricts who sees the mount. Additionally, SMB-layer permissions apply: if a user does not have read access to a folder inside the share, they cannot access it even if Nextcloud allows it.

Q: What if the SMB share goes offline or the network drops?

A: Users will see an error when trying to access that mount. Nextcloud does not cache SMB files locally (by default). If you need high availability, consider OS-level mounting with autofs, which can retry connections automatically.

Q: Is SMB secure? Should I use a VPN?

A: SMB over the network is not encrypted by default. If your Nextcloud and SMB server are on the same LAN, this is fine. If they cross untrusted networks (e.g., Nextcloud on a cloud VPS and SMB on-premises), use a VPN or SMB 3.1.1 (which supports encryption). Confirm your NAS or Samba server supports SMB 3.x and enable encryption in the share config.

Q: Can I share an SMB mount with other Nextcloud users?

A: Yes. By default, all users can access an SMB mount (if the Nextcloud admin allows it). Individual users can share files/folders from the mount to other users or groups using standard Nextcloud share controls.

Q: How often does Nextcloud scan SMB files for new/deleted files?

A: By default, Nextcloud scans on each file operation (lazy scanning). You can configure background jobs to run periodic scans. On managed hosting like Opsily, scans run automatically daily or as configured in your account.

The Bottom Line

SMB external storage turns your Nextcloud instance into a unified portal for team files scattered across NAS, Samba, and Windows servers. It is straightforward to set up if you have the prerequisites (php-smbclient, network access) and understand that both SMB and Nextcloud permissions must allow access. Start with a test mount on a small share, verify the connection, and check your permissions before rolling out to users.

For enterprises migrating from shared drives, SMB mounts are a natural fit. For companies on managed hosting like Opsily, the setup is even simpler: your provider handles dependencies, networking, and backups.