Skip navigation.

Full Stack: Portable Home Directory over NFS on OSX authenticated via OpenLDAP on Debian Linux

Portable Home Directory IconOSX has what I would call an undocumented feature of the operating system- the portable home directory. Basically, it keeps a user's home directory sync'd up between a network share and the local pc. If you are not on the network you work on the local home directory. Whenever you login on the network, the mirror agent running on the local pc synchronizes the two directories. This simple, extremely useful concept came with a steep learning curve. I think it took me two weeks to get this all working...

Hardware Used

Software Components

Steps at 1000' (overview)

  1. Create local administrator account.
  2. Install LDAP
  3. Add LDAP account and group
  4. Configure Directory Access on OSX
  5. Setup NFS shares/mounts on NAS
  6. Setup automount on OSX
  7. Login from OSX
  8. Create mobile account

Create local administrator account

In OSX on the laptop you need to create a local administrator account. Trust me on this. If you don't you could get stuck with a bad portable account that doesn't let you login (good luck if that's your only user). If you don't know how to create a local administrator account, you probably shouldn't attempt the rest of the guide (seriously); contact your local family IT expert for assistance.

Install LDAP

First you need to install the LDAP server and migration tools.

lowpower:~# apt-get install slapd ldap-utils migrationtools

You'll have to answer some questions during the setup like root password and such. No big deal though.

Next you'll need to add the apple specific schema definitions to the LDAP server. You'll need to get the apple.schema and samba.schema files (attached to this article) and put them with the other schema files. I put them in /etc/ldap/schema. Then you need to edit /etc/ldap/slapd.conf and add a few include lines:

include         /etc/ldap/schema/samba.schema
include         /etc/ldap/schema/apple.schema

After you restart ldap (/etc/init.d/slapd restart), you will either see errors (meaning you did something wrong) or a clean restart.

Add LDAP account and group

There are a couple of ways to manage LDAP: You can use a GUI tool, or use the command line. I think it is easier to use the command line and a couple of input files. If you do use the gui make certain that you login as the administrator.. this isn't like a normal login though.. you have to specify the User DN like an LDAP request. So instead of specifying 'admin' as the DN you would use 'cn=admin, dc=localdomain' or whatever you setup. The java utility I use lets me just specify cn=admin and check a box to append the base dn ('dc=localdomain' in my case).

I used a handy guide to convert a local user (on the box) to ldap. Once I created the first ldif file, I just copied that one and was able to make more users. Here's a group ldif

dn: cn=matt,dc=localdomain
objectClass: posixGroup
objectClass: top
cn: matt
userPassword: {crypt}x
gidNumber: 501

Here's a user ldif

dn: uid=matt,dc=localdomain
uid: matt
cn: Matthew Fleming
objectClass: account
objectClass: posixAccount
objectClass: top
userPassword: {crypt}++++++++ (this will be whatever auth you use)
loginShell: /bin/bash
uidNumber: 501
gidNumber: 501
homeDirectory: /Network/Servers/infrant-nas/matt
apple-user-homeurl: /Network/Servers/infrant-nas/matt
gecos: Matthew Fleming,,,


  • The uidNumber and gidNumber correspond to whatever account id you want to have in OSX. In my case, I already had a user account created that I was converting to a portable home directory. On OSX the first user and group numbers are usually 501.
  • The homeDirectory and apple-user-homeurl is what I'm going to specify as my mount point in OSX later.
  • The dn and uid are the user account short name in OSX
  • The cn is the user account name in OSX
  • If you don't specify apple-user-homeurl then you will have wierd problems with logging into the account when you are not on the home network.. meaning you are roving. Now setting it to the same as the mount point will break the user's ability to configure what gets sync'd but that didn't really matter to me; I manually changed the xml configuration files.

I probably loaded and reloaded my LDAP entries like a hundred times during the course of this project. Once you have your LDIF file it really isn't a big deal to do though. These two commands are your friend.. Add to ldap via a file named matt.ldif

ldapadd -h localhost -x -W -D "cn=admin,dc=localdomain" -c -f matt.ldif

Delete a user with a short name (uid) of matt

ldapdelete -h localhost -x -W -D "cn=admin,dc=localdomain" -c "uid=matt,dc=localdomain"

Configure Directory Access on OSX

What you need to do now is setup OSX pc so that it can authenticate users against your LDAP database.

Open the directory access application (spotlight directory).

Directory Access

  1. Enable LDAPv3 and click configure.
  2. Create a new configuration (new button at bottom).
  3. Type in the ip address of the ldap server or hostname if that resolves properly and Continue.
  4. Pick the RFC 2307 (Unix) template. Your searchbase should already be populated but if not use your base dn there (e.g. dc=localdomain)
  5. I didn't enable SSL on my LDAP server so I get a popup asking me to confirm that Strong authentication not supported. Ok no problem for my home network.

Now OSX will query the LDAP database when you try to login.

Setup NFS mounts on NAS

Every NAS is going to be different in this regard. The only general thing worth talking about is security. If you want some really basic user level security you'll need to make sure that the user and group ids used by the NAS are the same as the user and group ids used in the LDAP configuration (and what will be ultimately pushed to OSX). The main reason you want this is so that your home directory can't be used or read by some other user on your network. It really isn't a big deal in our house but I'd hate for something to get accidentally overwritten by someone other than me.

On the Infrant Ready NAS, I selected the User security mode. Then I created a user with uid-infrant. In my matt case the user id was matt-infrant. Why didn't I just use matt? Well on the Infrant, any share you create also takes up a user name. From the LDAP configuration above, you'll see I want my home directory to be called /Network/Servers/infrant-nas/matt. If I created the user id matt then I wouldn't have been able to name my share matt. It took me at least one pass before I figured out what was going on. Next create a share named whatever you want the home directory name to be. In my case, I used matt.

I don't exactly remember what happened when my home directory name was not the same as my OSX user account short name but it definitely made me start all over. I think I had synchronization issues.

Setup automount on OSX

Ok so now we have a network user stored in LDAP and a network share/mount for our home directory. Now we need to have OSX automount that share so that it can be used as a home directory. Open up the NetInfo Manager (spotlight netinfo).

Note: You could probably do this in LDAP (so you wouldn't have to configure every client machine) but I didn't try to do it.

Dynamic Automount via NetInfo

  1. Click the mounts folder in the middle pane.
  2. Add a new mount (Edit --> Add)
  3. Add Property: name Value(s): ip_address_of_nas:/share_name
  4. Add Property: dir Value(s): Network/Servers
  5. Add Property: type Value(s): nfs
  6. Add Property: opts Value(s): net

Only the first Property should be variable based upon your NAS name and the share name that you setup in the last section. For more information on automounts, you can check out the Automount NFS share in OSX section of my Ready NAS article. The key here is that you want to use dynamic automounts for user home directories.

Login from OSX

Now would be a good time to reboot the pc. You will need to verify that you can:

  1. Login using the LDAP account.
  2. Read and write to the home directory. Try putting a file into your home directory.

If this is successful, congratulations! You now have a network based account with a network based home directory. With this setup, you should be able to login using multiple pc's and see the same home directory. No need to copy files anymore. Caveat: multiple OSX pc's. That is cool but what if you aren't on that network? What if you have a laptop? Well, now it's time to make this account portable.

Create mobile account

Ok, we have a network login and a network home directory which work perfectly fine when we're on that network. Let's say we want to not be on that network.. login, do some work, then attach to the network later. We would want all of our work to automagically sync up with the network home directory. That's precisely what mobile accounts do.

To create a mobile account you'll need to do two things:

  1. Update the stuff you would like to sync.
  2. Enable the account.

Update sync preferences

You really only need to do this if you want ~/Library to sync. The only compelling reason that I had to do it was that I use Mail. By default (and I don't know how to change it) Mail stores all messages in ~/Library/Mail. If there is no reason for you to synchronize the ~/Library directory then you can skip this step. Otherwise, you will need to modify two files:

  1. /System/Library/CoreServices/mcxd (show contents)/Contents/Resources/CinchDefaults.plist
  2. ~/Library/Preferences/

In the first file (system level) there is an entry that needs to be deleted:


This is located in the excludedItems/array element. This entry tells us that OSX by default does not sync the directory.

In the second file I copied all of the ~/Library entries from the excludedPrefItems/array element into the excludedItems/array.

Enable the account

So after all of this, it is time to make the network account mobile. This is the easiest step of the bunch and hopefully most satisfying. On the machine that you want the account to be mobile, open System Preferences and go to Account. There you will find an option for Create mobile account. Once you check that box, you'll need to log out and back in for the inital sync to happen. If everything goes well, the account will sync with the server every 20 minutes.

One last thing.. if you get a dialog box pop up in the future that says a synchronization conflict exists beware of the both computers option. It will make a duplicate of every file on both machines that is in conflict. It does not mean ignore conflict.

Reference Material

Here are the reference materials used to make all of this happen. There's no way that I would have been able to figure this out without them:

Password problems

Great article, it helped me set all up in no-time.

I also can now change the user's network password directly from OSX, however I'm stuck with two problems:
1. user can enter any new password despite strong password policies set on the server (SLES10 box)
2. user doesn't get advanced password expiration warning

I've achieved both of the above on Windows, do you know how to do it on OSX?

Matt Fleming's picture

Re: Password Problems

Sorry I can't help you out on this one. I didn't have a password policy or anything like that to enforce (this was for my home network).



Most informative.'s picture

Using one OS X machine instead of the Debian server and/or NAS

I have a number of Macs in my home network, and am trying to figure out the best way to sync them. I really like the idea of using Portable Home Directories, and have considered installing OS X Server on my Mac Pro for this purpose, but if I could get this working without buying Server that would be great.

What I'm wondering is whether I could set my Mac Pro up with OpenLDAP and have it both serve the function of the LDAP server and work as a machine with a Portable Home Directory. It is on almost all of the time, so the other machines should always be able to connect to it, and if it happens to be off, they should be able to work from their local copies, right? This would save me the trouble and expense of setting up a separate server, and until the day that I pony up for a NAS, I can even use the drives in the Mac Pro for the network home directories.

Ideally, I'd figure out which ports the machines use for the authentication and syncing, and then I could open those ports on my router, make myself a self-signed SSL cert, and even let my laptops sync from the road, but since there are only two of us in the household at this point I won't worry about that too much yet.

At any rate, if you have any thoughts on this, please let me know.

Matt Fleming's picture

Re: Using one OS X machine instead of the Debian server

I don't think it really matters which OS you are using to host the LDAP server or the network file server... That being said, I've actually switched my 'always on server' to a mac mini, running OSX Server 10.4 (article coming as soon as I have time to write it). Portable Home Directories are definitely easier to manage in this configuration (over the debian way). In fact, the hardest part of the PHD setup (with OSX server) was configuring OSX Server to use a network file server (not an attached disk). I think it would literally take you like 5 minutes to setup PHDs on an OSX Server when using attached disks.

I haven't tried sync'ing from the road but that isn't really something I'm planning on doing either.. I'm never really away from home for extended periods of time.


Hi Matt,

Hi Matt,
I failed to find the article about setting up PHD on a NAS with tiger/leopard server. Did you already find some time to write this ? It's this kind of setup I am quite interested in ...


update for leopard?

Hi Matt,

I've read your article and this is right up my alley. My linux and windows boxes authenticate against my openldap server, and now I'm trying to get my wife's and my new macbooks running leopard to do this as well.

It appears quite a bit has changed with OS X directory services from 10.4 to 10.5. I followed your instructions, as well as some others that document things that have changed with leopard. So far, I've gotten authentication working. I've gotten automounting to work by configuring it locally on the client (can't get it to pull the automount maps from ldap, though).

However, where I'm really stuck is the homesync thing. When I log in as the network user and go to account preferences, I can enable the mobile account feature. It doesn't really give me choice of where to sync the account to other than the hard drive, so I accept that. It then appears as if it's working and logs me out. However, when I log back in the settings button for mobile accounts is greyed out and nothing appears to be synced. When I log in with cached credentials without being attached to the network, none of my home directory stuff is available.

Have you had a chance to mess with this in leopard? Have you considered updating the article for leopard? If not, do you have any advice?


apple schema generating error on idap restart

hi im really keen to get this working on my home network

i installed the schemas and tried restarting idap but get the following error

Starting OpenLDAP: slapd - failed:
/etc/ldap/schema/apple.schema: line 200: AttributeType not found: "authAuthority"

this is refering to the following in the schema file

objectclass (
NAME 'apple-user'
SUP top
DESC 'apple user account'
MAY ( apple-user-homeurl $ apple-user-class $
apple-user-homequota $ apple-user-mailattribute $
apple-user-printattribute $ apple-mcxflags $
apple-mcxsettings $ apple-user-adminlimits $
apple-user-picture $ apple-user-authenticationhint $
apple-user-homesoftquota $ apple-user-passwordpolicy $
apple-keyword $ apple-generateduid $ apple-imhandle $ apple-web$
authAuthority $ acctFlags $ pwdLastSet $ logonTime $
logoffTime $ kickoffTime $ homeDrive $ scriptPath $
profilePath $ userWorkstations $ smbHome $ rid $
primaryGroupID $ sambaSID $ sambaPrimaryGroupSID $
userCertificate ) )

do i need to comment out this section ?

Matt Fleming's picture


Hi there,

It's been a while since I've looked at this stuff but I'd guess that your slapd.conf file is missing some include that should be above the apple.conf


AttributeType not found: "authAuthority"

If you get this error (and you will), you have to make two edits in the schema. In the file apple.schema, there is a commented-out section for attributetype authAuthority and also one for apple-acl-entry. You will need to move both of them to the beginning of the file and remove the comment marks!

update for leopard?


I'm currently investigating that also. I see that Matt Flemming has gone and got MacOSX Server. Hey Matt do you know where you can get a cheaper "home" edition? I looked at the apple store and its US $499. This is doable but in Australia that's selling for $700 (at todays exchange rate US$499 is AU$590 which I could just handle paying). It surprises me Apple don't have a home version that is somewhat cheaper.

As for how to map Matt's instructions to Leopard, I think its all in Workgroup Manager now. I've started reading MacOSX Server 10.5 User Management manual to learn about setting up users, computers and groups. This page - discusses using WM but in server (so you can't use the Server Admin tool in clients). And then you need to copy the results to your clients manually I believe. I can't remember which site discussed doing this though I'm pretty sure I read it in MacTech. Here's the Google search for "Mactech mcx".

You can have a look at the information I'm collecting at (my delicious bookmark). More investigation is required.

I hope that helps. Please post any new information you have.