Using the
mfsymlinks option in your Samba server configuration resolves issues where symbolic links created on Linux clients fail to function correctly within the shared directory. This parameter ensures that symlinks are stored as special metadata rather than regular files, allowing them to behave consistently across different operating systems and client types without requiring complex permission adjustments or alternative workarounds.
Understanding the Symlink Problem in Samba
When you share a directory using Samba (SMB/CIFS) from a Linux server, the way symbolic links are handled can vary significantly depending on the client's operating system and the specific Samba version. On Linux clients, creating a symlink is a standard operation that results in a file containing a path string. However, older or default Samba configurations might not properly interpret these files as links when accessed by other clients, particularly Windows machines or even other Linux systems with different mount options.
This discrepancy often manifests as broken links, inability to traverse into linked directories, or errors when trying to access the target of the symlink. The core issue lies in how Samba translates the POSIX-style symbolic link concept into the SMB protocol. Without explicit configuration, Samba may treat the symlink content as a regular text file rather than a directive to redirect to another location. This leads to the "not working" behavior described in many troubleshooting scenarios, where the link exists but does not resolve to its intended target.
For more context on how hosts connect to Samba servers generally, you might find
Linux Hosts Connected to Samba Server: What Does It Mean? helpful for understanding broader connectivity patterns.
The Role of mfsymlinks
The solution involves enabling the
mfsymlinks parameter in your
smb.conf file. Introduced in Samba 3.6 and refined in later versions, this option provides a robust method for handling symbolic links. When enabled, Samba stores symlinks as special attributes (metadata) rather than as regular files. This approach is compatible with Microsoft's File System Filter Driver and ensures that symlinks are visible and functional across all supported clients.
Unlike the older
follow symlinks or
wide links options, which have limitations regarding security and cross-filesystem references,
mfsymlinks offers a more secure and reliable mechanism. It allows symlinks to point to locations outside the share, provided that the underlying Unix permissions allow it. This flexibility is crucial for users who need to link to directories that are not part of the immediate Samba export.
It is important to note that while
mfsymlinks improves compatibility, it requires support from the client side. Most modern Linux distributions and Windows versions (starting from Windows Vista/Server 2008) support this feature natively. If you are using an older client, you may need to update your SMB client software to ensure proper interaction with these metadata-stored links.
Configuring smb.conf for mfsymlinks
To implement this fix, you must edit the main Samba configuration file, typically located at
/etc/samba/smb.conf. You will need root or sudo privileges to make these changes. Open the file in your preferred text editor and locate the section defining your shared directory. This section usually starts with a name enclosed in square brackets, such as
[shared] or
[homes].
Inside this section, add the following line:
mfsymlinks = yes
You can also apply this setting globally under the
[global] section if you want all shares to use this behavior by default. However, applying it per-share is often safer as it allows you to control which directories benefit from this feature. After adding the line, save the file.
If you have existing symlinks in the share, they may need to be recreated after changing the configuration. Existing symlinks stored as regular files will not automatically convert to the new metadata format. Therefore, it is best practice to remove old symlinks and recreate them after restarting the Samba service.
Restarting and Verifying the Service
After modifying
smb.conf, you must restart the Samba services for the changes to take effect. On most Linux distributions, you can do this using systemd commands. Run the following command to restart the smbd service:
sudo systemctl restart smbd
On older systems using SysVinit, you might use:
sudo service smbd restart
Once the service is restarted, verify that the configuration was loaded correctly by checking the Samba log files, typically found in
/var/log/samba/. Look for any error messages related to configuration parsing. If no errors appear, test the symlinks from a client machine. Create a new symlink on a Linux client pointing to a directory within the share and attempt to access it from both Linux and Windows clients to ensure consistent behavior.
For additional troubleshooting if you encounter access issues, reviewing
Access SAMBA Drive Denied: SSH Ping Working on Two Devices might provide insights into common permission-related hurdles that could coexist with symlink issues.
Frequently Asked Questions
Does mfsymlinks work with Windows clients?
Yes,
mfsymlinks is specifically designed to improve compatibility with Microsoft Windows clients. Windows Vista and later versions support the necessary SMB extensions to interpret these metadata-stored symlinks correctly. This ensures that links created on Linux servers are accessible and functional on Windows machines without manual intervention.
Can I use mfsymlinks with older Samba versions?
No, the
mfsymlinks option was introduced in Samba 3.6. If you are running an older version of Samba, you cannot use this feature. You would need to upgrade your Samba installation to benefit from this improved symlink handling. Older versions rely on less reliable methods like
follow symlinks, which may not work as expected.
Will existing symlinks break after enabling mfsymlinks?
Enabling
mfsymlinks does not automatically convert existing symlinks stored as regular files. These old symlinks will remain as text files until they are deleted and recreated. To avoid confusion, it is recommended to remove any existing symlinks in the share before enabling the option and then recreating them to ensure they are stored in the correct metadata format.
Is there a performance impact when using mfsymlinks?
The performance impact is negligible for most use cases. Storing symlinks as metadata instead of regular files actually reduces the number of disk writes required during symlink creation. However, the overhead of managing these metadata attributes is minimal and should not affect overall network throughput or directory listing speeds significantly.
How do I check if mfsymlinks is active?
You can verify if
mfsymlinks is active by examining the Samba debug logs. Enable debug logging in
smb.conf and look for messages indicating that symlinks are being processed as metadata. Additionally, you can use tools like
smbclient to list directory contents and observe how symlinks are displayed, although direct log inspection is more definitive.