Hi,
here's a write-up about how to integrate a FreeNAS box into an Open Directory environment, including single-sign on support. I struggled a bit to make this work, this howto is intended for my own documentation and as reference for others who try to achieve the same thing. I believe that this should ultimately be included as a feature into the GUI.
[UPDATE 2020-09-06]:
Updated to reflect changes in FreeNAS 11.3.
As with FreeNAS 11.2, FreeNAS 11.3 has some breaking changes. The upgrade process will delete your Kerberos keytab file and some settings have been moved to a different place. You can get away by just re-uploading your keytab and change the relevant settings as noted below, but it is easiest to run through the entire setup again from top to bottom. Note the changes in the Samba configuration.
[UPDATE 2019-03-25]:
Added speedup suggestions to troubleshooting section.
[UPDATE 2019-03-08]:
Using the NetBIOS name instead of FQDN in the CIFS Kerberos principal greatly speeds up file and directory access. Updated instructions.
[UPDATE 2019-03-07]:
I upgraded to FreeNAS 11.2 and this version ships with Samba 4. The configuration is slightly different and I updated the instructions accordingly.
[UPDATE 2018-12-08]:
Created Tips & Troubleshooting section and moved several distributed comments over to make the text easier to read.
For reference, here is my setup:
Steps to take:
Names Used
Navigate to Directory Services->Kerberos Realms. Create a new realm and switch to advanced mode.
Save and ensure that there are no errors.
Navigate to Kerberos Settings and enter the following in "libdefaults auxiliary parameters":
Save and ensure that there are no errors.
Configure FreeNAS to use Open Directory
Most settings are already provided via GUI. In the FreeNAS web GUI, navigate to Directory Services->LDAP. Switch to advanced mode. Populate the following settings:
FreeNAS versions up to and including 11.2:
FreeNAS versions 11.3 and newer:
Ensure that your realm is selected and that the "enable" flag is checked. Save settings. You can ignore the "no samba attributes" warning, it is not relevant to this setup.
Important: This setup binds to LDAP with the diradmin credentials. You should either use SSL to prevent that the admin password is transmitted in cleartext over the network. I haven't documented that step here. Alternatively, you could even kerberize LDAP (which I haven't tried yet).
Before moving on, you need to test that LDAP actually works. In order to do this, open a shell on FreeNAS and type "getent passwd". The command should list BOTH your system and LDAP users. If you do not see your LDAP users, your configuration is not working. Repeat and check for errors before moving on.
When typing "klist", you should also already see a ticket granting ticket for diradmin.
Create and export Kerberos Principals on your macOS Server
Open a shell on your macOS server. Use the following command to create a new principal for SMB:
Make sure to replace freenas.home.net with the host name of your FreeNAS box and SERVER.HOME.NET with your realm.
The principal that is created by krbservicesetup by default does not allow creation of tickets. This is fixed by the first command in kadmin. The second command exports the principal to a keytab file.
Upload this file to your FreeNAS box in Directory Services->Kerberos Keytabs. You need to assign a name to the keytab, I assume "cifs_freenas" in the following sections.
Again, ensure that your setup works. On the FreeNAS box, open a shell and type:
Ensure that all commands proceed without errors and that klist shows a ticket granting ticket for diradmin as well as a ticket for cifs/freenas@SERVER.HOME.NET. Proceed only if both tickets are available, otherwise check and repeat.
Set up Samba for Kerberos [FreeNAS versions up to 11.1]
In the FreeNAS web GUI, navigate to Services->SMB. In the auxiliary parameters, enter the following:
Set up Samba for Kerberos [FreeNAS versions 11.2]
In the FreeNAS web GUI, navigate to Services->SMB. In the auxiliary parameters, enter the following:
Set up Samba for Kerberos [FreeNAS versions 11.3 and up]
Samba setup, continued
Make sure that the dedicated keytab file is actually located where you specify. On FreeNAS versions up to and including 11.2, the keytab is stored in /etc/kerberos and the file name is identical to the name you specify in the Kerberos Keytab configuration page. On FreeNAS 11.3, the keytab is hardwired to /etc/krb5.keytab.
Activate the SMB services in the "Control Services" pane and ensure that there are no errors.
Final Check
Add a new Samba share. Reboot FreeNAS and relogin on your client machines to ensure that your setup works from scratch and that there are no leftovers from intermediate configuration steps. You should now see FreeNAS in Finder. If you click on your FreeNAS box and then double-click on your test share, you should not be asked for login credentials. At the top of the Finder window, your Mac user name should appear.
Done!
Tips & Troubleshooting
here's a write-up about how to integrate a FreeNAS box into an Open Directory environment, including single-sign on support. I struggled a bit to make this work, this howto is intended for my own documentation and as reference for others who try to achieve the same thing. I believe that this should ultimately be included as a feature into the GUI.
[UPDATE 2020-09-06]:
Updated to reflect changes in FreeNAS 11.3.
As with FreeNAS 11.2, FreeNAS 11.3 has some breaking changes. The upgrade process will delete your Kerberos keytab file and some settings have been moved to a different place. You can get away by just re-uploading your keytab and change the relevant settings as noted below, but it is easiest to run through the entire setup again from top to bottom. Note the changes in the Samba configuration.
[UPDATE 2019-03-25]:
Added speedup suggestions to troubleshooting section.
[UPDATE 2019-03-08]:
Using the NetBIOS name instead of FQDN in the CIFS Kerberos principal greatly speeds up file and directory access. Updated instructions.
[UPDATE 2019-03-07]:
I upgraded to FreeNAS 11.2 and this version ships with Samba 4. The configuration is slightly different and I updated the instructions accordingly.
[UPDATE 2018-12-08]:
Created Tips & Troubleshooting section and moved several distributed comments over to make the text easier to read.
For reference, here is my setup:
- I have a Mac mini that runs macOS Server. This machine provides directory and authentication services for the network. It doesn't have to be a separate machine, but for this howto I assume that you have a macOS server instance running somewhere.
- I have several Macs that act as client machines. On these Macs any directory user can sign in by using the credentials stored in macOS server.
- The FreeNAS box provides data storage to the network. Any user logged in on any Mac shall be able to use this machine without additional login steps.
Steps to take:
- Use a fresh FreeNAS install. If you have an existing FreeNAS box, it is not necessary to kill your current setup, but I found that many setup variables easily create a hard-to-spot error. If you can't make it work, I suggest to start with a fresh test installation.
- Have a macOS Server instance that provides Open Directory services and has users and groups that can log in.
- Configure FreeNAS to use Open Directory for users and groups.
- Configure Kerberos realm on FreeNAS.
- Create Kerberos principals on your macOS server for each service you want to kerberize. Kerberized services will be single-sign-on.
- Export Kerberos principals and import them on FreeNAS.
- Setup services (example used here is Samba) to use the Kerberos principals for authentication.
- Read through the optimization suggestions at the very end and try them out
Names Used
- Home network domain: home.net. This is set by your router and can be .local, fritz.box or similar.
- macOS server name: server.home.net
- Kerberos realm (determined by your macOS server name): SERVER.HOME.NET (note the capitalization!)
- Distinguished name of macOS server in directory: dc=server,dc=home,dc=net (adjust this according to your server name)
- Directory administrator account: diradmin (this is the default name - if you changed it, adjust accordingly)
- Directory administrator's distinguished name: uid=diradmin,cn=users,dc=server,dc=home,dc=net (this is again the default, change according to your server's distinguished name)
- FreeNAS server name: freenas.home.net
- FreeNAS NetBIOS name: freenas
Navigate to Directory Services->Kerberos Realms. Create a new realm and switch to advanced mode.
Code:
Realm: SERVER.HOME.NET KDC: server.home.net Admin server: server.home.net Password server: server.home.net
Save and ensure that there are no errors.
Navigate to Kerberos Settings and enter the following in "libdefaults auxiliary parameters":
Code:
default_realm = SERVER.HOME.NET realm_try_domains = 1
Save and ensure that there are no errors.
Configure FreeNAS to use Open Directory
Most settings are already provided via GUI. In the FreeNAS web GUI, navigate to Directory Services->LDAP. Switch to advanced mode. Populate the following settings:
FreeNAS versions up to and including 11.2:
Code:
Hostname: server.home.net Base DN: dc=server,dc=home,dc=net Bind DN: uid=diradmin,cn=users,dc=server,dc=home,dc=net Bind Password: <password of the directory admin account> User suffix: cn=users Group suffix: cn=groups Password suffix: cn=users Machine suffix: cn=computers Allow anonymous binding: checked
FreeNAS versions 11.3 and newer:
Code:
Hostname: server.home.net Base DN: dc=server,dc=home,dc=net Bind DN: uid=diradmin,cn=users,dc=server,dc=home,dc=net Bind Password: <password of the directory admin account> Allow anonymous binding: checked
Ensure that your realm is selected and that the "enable" flag is checked. Save settings. You can ignore the "no samba attributes" warning, it is not relevant to this setup.
Important: This setup binds to LDAP with the diradmin credentials. You should either use SSL to prevent that the admin password is transmitted in cleartext over the network. I haven't documented that step here. Alternatively, you could even kerberize LDAP (which I haven't tried yet).
Before moving on, you need to test that LDAP actually works. In order to do this, open a shell on FreeNAS and type "getent passwd". The command should list BOTH your system and LDAP users. If you do not see your LDAP users, your configuration is not working. Repeat and check for errors before moving on.
When typing "klist", you should also already see a ticket granting ticket for diradmin.
Create and export Kerberos Principals on your macOS Server
Open a shell on your macOS server. Use the following command to create a new principal for SMB:
sudo krbservicesetup -x -r SERVER.HOME.NET -a diradmin -p <admin password> cifs cifs/freenas@SERVER.HOME.NET
Make sure to replace freenas.home.net with the host name of your FreeNAS box and SERVER.HOME.NET with your realm.
sudo kadmin -l
kadmin> modify --attributes=-disallow-svr cifs/freenas@SERVER.HOME.NET
kadmin> ext_keytab --keytab=cifs_freenas.keytab cifs/freenas@SERVER.HOME.NET
kadmin> exit
The principal that is created by krbservicesetup by default does not allow creation of tickets. This is fixed by the first command in kadmin. The second command exports the principal to a keytab file.
Upload this file to your FreeNAS box in Directory Services->Kerberos Keytabs. You need to assign a name to the keytab, I assume "cifs_freenas" in the following sections.
Again, ensure that your setup works. On the FreeNAS box, open a shell and type:
kinit diradmin
kgetcred cifs/freenas@SERVER.HOME.NET
klist
Ensure that all commands proceed without errors and that klist shows a ticket granting ticket for diradmin as well as a ticket for cifs/freenas@SERVER.HOME.NET. Proceed only if both tickets are available, otherwise check and repeat.
Set up Samba for Kerberos [FreeNAS versions up to 11.1]
In the FreeNAS web GUI, navigate to Services->SMB. In the auxiliary parameters, enter the following:
Code:
security = ADS realm = SERVER.HOME.NET kerberos method = dedicated keytab dedicated keytab file = /etc/kerberos/cifs_freenas
Set up Samba for Kerberos [FreeNAS versions 11.2]
In the FreeNAS web GUI, navigate to Services->SMB. In the auxiliary parameters, enter the following:
Code:
security = USER realm = SERVER.HOME.NET kerberos method = dedicated keytab dedicated keytab file = /etc/kerberos/cifs_freenas encrypt passwords = yes idmap config * : backend = tdb
Set up Samba for Kerberos [FreeNAS versions 11.3 and up]
Code:
security = USER realm = SERVER.HOME.NET kerberos method = dedicated keytab dedicated keytab file = /etc/krb5.keytab encrypt passwords = yes idmap config * : backend = tdb ldap user suffix = cn=users ldap group suffix = cn=groups ldap machine suffix = cn=computers
Samba setup, continued
Make sure that the dedicated keytab file is actually located where you specify. On FreeNAS versions up to and including 11.2, the keytab is stored in /etc/kerberos and the file name is identical to the name you specify in the Kerberos Keytab configuration page. On FreeNAS 11.3, the keytab is hardwired to /etc/krb5.keytab.
Activate the SMB services in the "Control Services" pane and ensure that there are no errors.
Final Check
Add a new Samba share. Reboot FreeNAS and relogin on your client machines to ensure that your setup works from scratch and that there are no leftovers from intermediate configuration steps. You should now see FreeNAS in Finder. If you click on your FreeNAS box and then double-click on your test share, you should not be asked for login credentials. At the top of the Finder window, your Mac user name should appear.
Done!
Tips & Troubleshooting
- Cannot mount share from finder (resource not found): In finder, choose "Go -> Connect to Server..." and enter "smb://freenas/share_name". Click Connect. This will directly mount the share, authenticate and also allow browsing via Finder afterwards. If no share is mounted, Finder will for some reason refuse to use the existing Kerberos ticket and I haven't found a way to force it to do so. As soon as the first share is mounted, the workaround is not necessary until the next reboot.
- Setup suddenly stops working after a macOS update (system update or Server.app update): System updates on the Mac server often invalidate the Kerberos keytabs. Recreating the Kerberos principals, creating a new keytab file and uploading the keytab to FreeNAS should fix it.
- Setup suddenly stops working after a FreeNAS update: FreeNAS keeps changing the location of settings, sometime settings are also not properly carried over after an upgrade. Oftentimes the upgrade process deletes the keytab. It is easiest to re-run through the entire setup from top to bottom.
- Shares are slow to mount: Try using the NetBIOS name instead of the FQDN in your Kerberos principal. For example, if your NetBIOS name is "freenas" and your FQDN is "freenas.home.net", do not use cifs/freenas.home.net@SERVER.HOME.NET as your principal but cifs/freenas@SERVER.HOME.NET. I am not sure why but it seems that NetBIOS names are tried first when looking for an existing service principal. A principal using FQDN will work, too, but takes a lot longer to authenticate.
- Directory browsing is slow: Disabling extended attributes and disabling strict syncing will speed up directory browsing A LOT, especially if you have directories with tons of files in them. Refer to the Samba manual if you need them - chances are, you won't. Extended attributes are typically only required in setups that try to make use of DOS file attributes. Pure Mac environments do not use these. Strict syncing will wait for all pending writes to be written to disk until a file system call returns. ZFS syncs every couple of seconds. This means that if your server crashes during a write operation, all changes since the last sync operation are lost. For my personal use, the speed-up far outweighs the potential downside. Here are the configuration options (to be set in SMB's auxiliary parameters):
Code:ea support = no store dos attributes = no map archive = no map hidden = no map readonly = no map system = no strict sync = no
Last edited: