samba
Starting with JuiceFS 5.2, the Windows client entered public beta. See Quick Start for installation and mounting details. For large-scale usage, AD-domain integration, or maximum operational maturity, we still recommend deploying Samba on Linux as the access gateway for JuiceFS. This chapter explains how to deploy Samba with JuiceFS.
JuiceFS Enterprise Edition does not provide technical support for Samba operations. If you run into Samba-specific issues, please refer to official Samba documentation or community support channels.
Samba overview
Samba is an open-source implementation of the SMB (Server Message Block) protocol. With Samba, you can share a JuiceFS mount point on Linux to Windows, macOS, and Linux clients, with user-based access control.
Mount JuiceFS
After preparing a Linux host for Samba, follow Quick Start to create and mount your JuiceFS file system. For Samba workloads, these mount options are recommended:
juicefs mount smb-gateway /jfs \
--update-fstab \
--cache-dir /dev/shm \
--no-posix-lock \
--no-bsd-lock \
--buffer-size 1000
Step 1: Install Samba
Install Samba and related tools:
# Debian and derivatives
apt install -y samba cifs-utils
# RHEL and derivatives
yum install -y samba* cifs-utils
Step 2: Enable xattr
For Samba + JuiceFS, enabling extended attributes (xattr) on the Samba server is recommended. Add this to the [global] section in /etc/samba/smb.conf:
[global]
ea support = yes
Why enable xattr
Samba stores Windows extended metadata (for example ADS data) in xattr. If xattr is disabled, Windows clients may see metadata loss, compatibility issues, or unexpected behavior in some applications.
Step 3: Configure a shared directory
Configure the mounted JuiceFS directory /jfs as a Samba share. Assume the share name is juicefs (accessible as \\HOST\juicefs). Add the following to /etc/samba/smb.conf:
[juicefs]
writable = yes
browseable = yes
read only = No
comment = JuiceFS
create mask = 0664
directory mask = 0777
guest ok = Yes
path = /jfs
read list = root
valid users = root
write list = root
After configuration, start Samba:
systemctl enable --now {smb,nmb}
# Check listening ports and verify network connectivity
lsof -PiTCP | grep smb
Add root as a Samba user by running smbpasswd -a root, then set the password when prompted. This account is used for Windows access to the Samba share.
Use commands like these to verify mounting:
# Verify protocol and network, and list available shares
smbclient -U root -L <Samba-IP>
# Mount from Linux first to validate availability
mount -t cifs -o username=root,password=xxx //<Samba-IP>/juicefs /mnt/samba
# Mount from Windows
net use Z: \\<Samba-IP>\juicefs "<password>" /user:root
For multi-node Samba deployments, we recommend avoiding CTDB-based Samba clustering, as it can consume significant resources under high concurrency. For horizontal scaling, deploy multiple stateless Samba nodes and map them to a single DNS name for DNS-based load balancing.
Step 4 (optional): macOS compatibility notes
macOS can access Samba shares directly. Similar to Windows, macOS also uses extended metadata (such as icon position and Spotlight data) that depends on extended attributes (xattr).
Samba 4.9+ generally has the required support enabled by default. If your Samba version is lower than 4.9, ensure ea support = yes is enabled in the global configuration (same as above):
[global]
ea support = yes
References:
Multi-user support
Samba supports multi-user access. Define multiple shared file systems in the configuration file and map each one to a specific subdirectory and user to control access per user.
The configuration is straightforward. Ensure each subdirectory exists in advance, and create corresponding Samba users with smbpasswd.
[bob]
writable = yes
browseable = yes
read only = No
comment = JuiceFS for bob
create mask = 0664
directory mask = 0777
guest ok = Yes
path = /jfs/bob
read list = bob
valid users = bob
write list = bob
[alice]
writable = yes
browseable = yes
read only = No
comment = JuiceFS for alice
create mask = 0664
directory mask = 0777
guest ok = Yes
path = /jfs/alice
read list = alice
valid users = alice
write list = alice
Samba user management and access control
By default, Samba authenticates local system users. After creating a user, configure both Linux file permissions and Samba credentials:
# Create a system user (example)
useradd -M -s /sbin/nologin alice
# Grant local file permissions on the shared directory
setfacl -R -m u:alice:rwx /jfs/alice
# Add user to Samba account database and set password
smbpasswd -a alice
To list Samba users:
pdbedit -L -v
Troubleshooting
CIFS mount failures
Common errors:
CIFS VFS: \\xxx\xxx BAD_NETWORK_NAME: \\xxx\xxx: the share name is incorrect. Usesmbclient(shown above) to list available shares and verify the name.CIFS VFS: cifs_mount failed w/return code = -13: authentication failed. Check username and password.
net use command errors
For the JuiceFS Windows client, net use mounting is provided by WinFsp. When net use fails, troubleshooting inside WinFsp is limited. In this case, run juicefs.exe in foreground mode with -v for richer logs:
.\juicefs.exe mount juicefs Z: -v
JuiceFS Windows client does not support multi-user mount sessions. If user A has already mounted JuiceFS or Samba, user B may see error 1219 when trying to mount the same target with different credentials.
Check for existing network sessions in other sessions, or disconnect them with net use * /delete. For full details, see the net use documentation.
File permission errors
If Samba is mounted but you still get permission denied, make sure SELinux is disabled. Run on all Samba nodes:
setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/sysconfig/selinux
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
Domain account cannot access Samba mount point
If user A mounted Samba, domain account B may not have permission to access that mount point. If your scenario allows it, mount directly as user B so that the mount owner is the same account that needs access.
