Solving the mystery of Xigmanas Samba file permissions on ZFS

Feb 3, 2020

There are so many forum posts on how to get Samba file permissions working with Xigmanas. It’s been frustrating to figure out exactly what to do, because none of the posts give the full picture.

This weekend I hunkered down to try and understand what was going on, and the work finally paid off. I uncovered some secrets about the inner workings of the file system, and through trial-and-error found the settings that do exactly what I want them to do.

Here’s what I learned.

Secret #1: Five different things affect file permissions

No one just comes out and says it. I had to really delve into how things are set up to figure this out.

Otherwise, you’ll be stuck with files that get permissions that you swear you didn’t set. It will drive you insane. Once I started to see how all the parts worked together, it made more sense.

The five things controlling file permissions are:

Unix file and folder permissions
Samba share permissions
ZFS dataset permissions
ZFS ACL
umask

That’s right, five things! Crazy. Each of those things can affect the permissions of files and folders created in your Samba shares in Xigmanas. Before this weekend, I only knew about #1, #2, and #3. #4 and #5 were little sneaky surprises.

I’ll show you how to deal with them in a bit.

Secret #2: You need to restart Samba after every change

When you change settings on your Samba shares in Xigmanas and then apply them, you’d expect the changes to take effect. After all, that’s how Xigmanas works for everything else. But, not here.

You must restart Samba after making changes, especially around permissions and inheritance, in order for them to take effect.

To do this, just go to Services > CIFS/SMB, then click the Save & Restart button at the bottom of the page.

With those tips in hand, let’s turn our attention to configuring your system.

Example scenario

Consider a household with three people:

Those three people each have files to store. We’ll be creating:

A private folder for each person.
A group folder for the family to store all of their photos, writeable by family members and readable by guests.
A public folder that’s writeable by everyone on the network.

Here’s what that looks like:

	Writable by	Readable by	Permissions
Dad’s files	Dad	Dad	0700
Mom’s files	Mom	Mom	0700
Son’s files	Son	Son	0700
Family photos	Dad, Mom, and Son	Everyone (including guests)	0775
Open share	Anyone on the network	Everyone (including guests)	0777

Let’s go

Now that we have the shares mapped out, and the permissions for each, let’s start doing the real work.

Assume all interaction will be done over Samba

Let’s assume that all client machines will interact with the Xigmanas file shares over Samba.

You may be running Linux clients that use NFS or SSH/SFTP to interact with the files on the server. If so, newly-created files will get their permissions set by the umask of the server. Their permissions will be totally different from those you define by the ZFS dataset, the Samba share, and anything else.

This concept was foreign to me, and honestly I need to do a little more research into how to manipulate it. From what I read so far, umask is set up each time the server boots, and it applies to all files created on the server by any user.

For now, since I don’t know how to control this beast, I’ll just assume that all file creation and modification will be done by clients over Samba.

If you absolutely must interact with the files outside of Samba, just be sure to run a chmod and chown over all new files you create to get them in line with the existing share permissions scheme.

We’ve reduced our list of pain by one:

Unix file and folder permissions
Samba share permissions
ZFS dataset permissions
ZFS ACL
~~umask~~

Kill the ACL

The ZFS ACL allows individual files in a folder to have unique and special permissions above and beyond the traditional Unix User/Group/Other modes. It’s a really cool feature to have, but in this case it just complicates things.

Because we’re giving everyone private shares, the files within those shares don’t need complicated permissions. Files in someone’s share will simply be owned, writeable, and readable by the owner of the share.

So, let’s make things simpler and take the ZFS ACL out of the equation. Now we’re down by two:

Unix file and folder permissions
Samba share permissions
ZFS dataset permissions
~~ZFS ACL~~
~~umask~~

And now, with those two surprise “features” out of the way, we’re ready to set up what most people are familiar with: a Samba server.

Settings

Here are the exact settings I’ve used. Important settings have been called out in the actual text, below.

ZFS datasets settings

	Private (screenshot)	Group (screenshot)	Public (screenshot)
ACL inherit	Discard
ACL mode	Discard
Extended attributes	No
Owner	dad	root	guest
Group	dad	family	guest
Mode	0770	0775*	0777

*: 0775 will allow guests to view these files. If you don’t want that, use 0770.

	Private (screenshot)	Group (screenshot)	Public (screenshot)
Enable permission inheritance	Yes
Enable ZFS ACL	No
Enable ACL inheritance	No
Store alternate data streams in extended attributes	No
Store NTFS ACLs in extended attributes	No
Additional parameters	force create mask = 0770 force directory mask = 0770	force create mask = 0775 force directory mask = 0775	force create mask = 0770 force directory mask = 0770 force user = guest force group = guest

With all that in place, I was surprised to see that the Samba shares through Xigmanas were working just like I expected them to! This was a happy day, indeed.

P.S. One more tip. Sometimes Windows and Mac clients can be stubborn about refreshing shared folder permissions if they change after the share has already been mounted. Logging out and back in to your client machine’s session usually clears this right up!