Solving the mystery of Xigmanas Samba file permissions on ZFS

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:

  1. Unix file and folder permissions
  2. Samba share permissions
  3. ZFS dataset permissions
  4. ZFS ACL
  5. 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:

  • Dad
  • Mom
  • Son

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:

  1. Unix file and folder permissions
  2. Samba share permissions
  3. ZFS dataset permissions
  4. ZFS ACL
  5. 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:

  1. Unix file and folder permissions
  2. Samba share permissions
  3. ZFS dataset permissions
  4. ZFS ACL
  5. 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.

Samba share settings

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!