Samba Shared Folder with setgid Problem: A Comprehensive Solution for Consistent Permissions

Setting up a Samba share with proper group ownership and permissions, especially when leveraging the setgid bit, can be a complex undertaking. While standard procedures work well for local access, Samba often introduces unexpected behavior, particularly concerning POSIX ACLs and group inheritance. This article provides a detailed guide to configuring Samba to correctly handle setgid and ensure consistent permissions across all access methods, including console logins, SSH, rsync, and, most importantly, Samba shares. We will walk through potential pitfalls and offer a configuration that works reliably.

Understanding the Challenge: Samba, setgid, and ACLs

The primary goal is to create a shared directory where all files and subdirectories inherit the group ownership from the parent directory, and new files automatically grant write permissions to the group. The setgid bit on a directory achieves the group ownership inheritance, while ACLs (Access Control Lists) are intended to manage the permissions. However, Samba’s interaction with these mechanisms can be problematic:

  • Ignoring POSIX ACLs: By default, Samba might not fully respect POSIX ACLs, leading to new files lacking group write permissions even when the ACL is correctly configured.
  • Incorrect Group Inheritance: Activating acl_xattr VFS object is often suggested as a fix to the prior issue, but this can lead to Samba using the user’s primary group instead of inheriting the group from the parent directory, negating the effect of setgid.
  • Conflicting Configuration Options: Several Samba configuration options, such as map acl inherit, store dos attributes, and inherit acls, are intended to influence ACL behavior, but their interactions and effectiveness can be unpredictable.

Step-by-Step Configuration: Achieving Consistent Permissions

The following steps outline a comprehensive approach to configuring a Samba share with setgid that consistently works. We will use appropriate smb.conf configuration options.

1. Setting Up the Shared Directory

First, ensure the shared directory is properly configured from the command line. This involves setting the correct ownership, permissions, and ACLs:

# chown root:users shared
# chmod -R ug+rwX shared
# find shared -type d -exec chmod g+s "{}" \;
# setfacl -d -m g::rwx shared
# setfacl -d -m o::rx shared
# setfacl -m g::rwx shared
# setfacl -m o::rx shared

Explanation of commands:

  • chown root:users shared: This command changes the ownership of the “shared” directory to root as the owner and “users” as the group. This is a crucial first step to setting up the shared directory’s permissions.
  • chmod -R ug+rwX shared: This command modifies the permissions of the “shared” directory and all its contents recursively. Specifically, it grants read, write, and execute (if it’s a directory) permissions to the user and group, while leaving existing execute bits for others untouched.
  • find shared -type d -exec chmod g+s "{}" \;: This command finds all directories within the “shared” directory and sets the setgid bit on them. This ensures that any new files or subdirectories created within these directories will inherit the group ID of the parent directory.
  • setfacl -d -m g::rwx shared: sets the default ACL for the group to have read, write, and execute permissions. This means that new files and directories created in the “shared” directory will inherit these permissions for the group.
  • setfacl -d -m o::rx shared: sets the default ACL for “others” to have read and execute permissions. Like the group ACL, this ensures new files and directories inherit these permissions for users who are neither the owner nor members of the group.
  • setfacl -m g::rwx shared: sets the ACL for the current directory “shared” to give read, write, and execute permissions to the group. This command ensures that the directory itself has the specified permissions.
  • setfacl -m o::rx shared: sets the ACL for “others” on the current directory “shared” to have read and execute permissions. This makes sure that the directory itself has these permissions set for users who are neither the owner nor members of the group.

2. Configuring Samba (smb.conf)

The core of solving the issue lies in the Samba configuration. The /etc/samba/smb.conf file needs to be adjusted to handle permissions correctly. A well-configured share definition should address both ACL handling and group inheritance.

Here’s a sample share definition:

[shared]
        path = /path/to/your/shared
        valid users = @users
        read only = no
        create mask = 0660
        directory mask = 0770
        force group = users
        inherit acls = yes
        map acl inherit = yes
        store dos attributes = yes
        vfs objects = acl_xattr
        # These lines are necessary to support non-ascii file names:
        unix charset = UTF-8
        display charset = UTF-8
        dos charset = CP850

Explanation of parameters:

  • path = /path/to/your/shared: Defines the actual file system path to the shared directory. Replace /path/to/your/shared with the actual path to the directory you are sharing.
  • valid users = @users: Restricts access to users belonging to the ‘users’ group. The @ symbol indicates a group. Make sure that all users who need access to the share are members of this group.
  • read only = no: Allows both reading and writing to the share. If you want to restrict write access, set this to yes.
  • create mask = 0660: Sets the permissions for newly created files. 0660 translates to read and write permissions for the owner and group, and no permissions for others.
  • directory mask = 0770: Sets the permissions for newly created directories. 0770 translates to read, write, and execute permissions for the owner and group, and no permissions for others.
  • force group = users: Forces all newly created files and directories to belong to the ‘users’ group, regardless of the user’s primary group. This is important for ensuring the setgid bit is correctly enforced.
  • inherit acls = yes: Enables ACL inheritance. This instructs Samba to apply the ACLs of the parent directory to newly created files and subdirectories.
  • map acl inherit = yes: Ensures that ACL inheritance is properly mapped from the Unix-style ACLs to Samba’s internal representation. This is important for Samba to correctly understand and apply the ACLs.
  • store dos attributes = yes: Stores DOS attributes within the extended attributes of the file system. This can help with compatibility when accessing the share from Windows clients.
  • vfs objects = acl_xattr: Enables the acl_xattr VFS object, which allows Samba to properly handle POSIX ACLs stored as extended attributes. This is a critical component for respecting the ACLs set on the shared directory.
  • unix charset = UTF-8, display charset = UTF-8, dos charset = CP850: These parameters handle character encoding. Specifically, they are necessary to support non-ascii file names.

3. Essential Samba Configuration Options in Global Section

In the global section of the Samba configuration file, you also need to configure the following options.

[global]
    security = user
    map to guest = Bad User
    unix extensions = yes
    wide links = yes
    follow symlinks = yes
    allow insecure wide links = yes

Explanation of parameters:

  • security = user: Specifies the security mode for Samba. security = user means that Samba will authenticate users based on their username and password.
  • map to guest = Bad User: Determines what happens when a user fails to authenticate. map to guest = Bad User means that Samba will refuse the connection.
  • unix extensions = yes: Enables Unix extensions, which allows Samba to support Unix-specific features, such as symbolic links and hard links. Setting this to yes is important for seamless integration with Unix-like systems.
  • wide links = yes, follow symlinks = yes, allow insecure wide links = yes: These settings enable support for symbolic links. They are necessary for allowing the samba server to follow symbolic links outside of the samba share directory.

4. Restarting Samba

After modifying the smb.conf file, restart the Samba service to apply the changes:

sudo systemctl restart smbd nmbd

5. Testing the Configuration

After restarting Samba, thoroughly test the configuration:

  • Create files and directories: Create new files and directories within the shared folder using Samba from a client machine.
  • Verify permissions: Verify that the new files and directories have the correct group ownership (“users”) and permissions (read/write for the group).
  • Test from different clients: Test from both Windows and Linux clients to ensure compatibility.
  • Check ACLs: Use getfacl on the server to verify that the default ACLs are being applied correctly to new files and directories.

6. Troubleshooting Common Issues

If the configuration still doesn’t work as expected, consider these troubleshooting steps:

  • User Membership: Ensure all users accessing the share are members of the ‘users’ group. Use the groups command on the server to verify a user’s group memberships.
  • SELinux/AppArmor: If SELinux or AppArmor is enabled, it might be interfering with Samba’s access to the shared directory. Check the audit logs for any denied operations and adjust the SELinux/AppArmor policies accordingly.
  • Firewall: Ensure that the firewall is not blocking Samba traffic (ports 137, 138, 139, and 445).
  • Samba Logs: Examine the Samba logs (/var/log/samba/log.smbd and /var/log/samba/log.nmbd) for any error messages or warnings.
  • Client-Side Caching: Windows clients might cache permissions. Try disconnecting and reconnecting the network drive or restarting the client machine.

Advanced Considerations and Optimizations

Optimizing for Performance

While the primary focus is on correctness, performance is also important. Consider these optimizations:

  • Use SSD Storage: If possible, store the shared directory on an SSD for faster I/O.
  • Tune Samba Parameters: Experiment with Samba’s tuning parameters, such as socket options, read raw, and write raw, to optimize for your specific network environment.
  • Enable Opportunistic Locking: Opportunistic locking can improve performance for Windows clients by allowing them to cache file data locally. Ensure that oplocks = yes is set in the smb.conf file.

Enhancing Security

Security should always be a priority. Consider these security enhancements:

  • Use Strong Passwords: Enforce strong password policies for all Samba users.
  • Enable Encryption: Enable encryption for Samba traffic using tls enable = yes and tls require = yes in the smb.conf file.
  • Regularly Update Samba: Keep Samba up-to-date with the latest security patches.
  • Implement Intrusion Detection: Use an intrusion detection system (IDS) to monitor Samba traffic for suspicious activity.

Handling Special Characters and File Names

As noted in the example configuration, proper character encoding is essential for handling special characters and non-ASCII file names. The unix charset, display charset, and dos charset parameters in the smb.conf file must be configured correctly to avoid file name corruption issues. UTF-8 is generally the best choice for unix charset and display charset, while CP850 is a common choice for dos charset.

Alternative Approach: Using Group-Based Access Control (without setgid)

While setgid is a common approach, you could also consider managing permissions exclusively through group-based access control lists (ACLs). In this scenario, you would not rely on the setgid bit but instead meticulously manage group ownership and ACLs for all files and directories.

Steps for ACL-Based Approach

  1. Create the Shared Directory:

    mkdir /path/to/shared
chown root:users /path/to/shared
chmod 0770 /path/to/shared

  2. Set Default ACLs:

    setfacl -d -m g::rwx /path/to/shared
setfacl -d -m o::--- /path/to/shared
setfacl -m g::rwx /path/to/shared
setfacl -m o::--- /path/to/shared

  3. Samba Configuration: The Samba configuration would remain similar, but you might omit the force group parameter since you are managing group ownership directly through ACLs.

Considerations for ACL-Based Approach

  • Complexity: This approach requires more careful management of ACLs, especially when dealing with a large number of files and directories.
  • Automation: Consider using scripts to automate the process of setting and maintaining ACLs.
  • Monitoring: Regularly monitor ACLs to ensure they are consistent and correct.

Conclusion

Successfully configuring a Samba share with setgid requires a comprehensive understanding of Samba’s interaction with file system permissions, ACLs, and group inheritance. By following the steps outlined in this article, you can create a shared directory where new files and directories automatically inherit the correct group ownership and permissions, ensuring consistent access control across all access methods. Remember to test your configuration thoroughly and monitor the system for any issues. By choosing the right set of parameters, and paying attention to file encodings and security, we can create a reliable and secure Samba shared folder that will continue to perform optimally as the needs of the users increase.