Wednesday, August 31, 2005

Mac OS X as an NFS Client

I'll discuss the changes necessary to mount NFS filesystems onto a Mac OS X machine. This was originally written in the 10.1 days, but is still applicable on 10.4.2 (non-server versions tested).

The example filesystem used here will be called /exported/path from the server nfsserver. It will be mounted to /private/mnt. You will obviously want to change these to something useful and sane for your situation.

Mounting NFS filesystems on OS X can be done simply by running:

sudo mount nfsserver:/exported/path /private/mnt

This is, however, temporary (it won't live through a reboot). In order to have the system deal with mounting it for you, you could add that mount command to an rc script or create a startup script in /Library/StartupItems. The best way, however, is to add the information to NetInfo, and let the automounter handle everything.

In a nutshell, a new directory is added to NetInfo, called /mounts, and subdirectories under that specify the remote filesystems to mount.

NetInfo Changes, Graphical-Style

  1. To accomplish this in Aqua, run NetInfo Manager (located in /Applications/Utilities) and authenticate as an administrator (the little lock at the bottom of the window).
    Authenticate lock
    Authenticate lock

  2. We need to create a new directory, so click on the left-most directory (called simply, /), and create a new directory (through the button, menu option, or shortcut Cmd-N).
    This will create a new directory called new_directory, which we need to rename.
    root in the directory browser
    root in the directory browser

    Ways to create a directory
    Ways to create a directory

  3. In the bottom part of the window, double-click on new_directory in the Value(s) column, which will highlight new_directory and place the insertion point there. Simply type mounts to rename it then save changes (Cmd-S or Domain menu, and select Save) to update the browser portion of the window.
    Renaming the newly-created directory
    Renaming the newly-created directory

    Now renamed, but not saved
    Now renamed, but not saved

    Now renamed and saved
    Now renamed and saved

    Any mounts the automounter handles will be listed under this new directory in NetInfo. Let's add one.

  4. Click on mounts in the browser, and create a new directory. The value of the name property for each subdirectory in mounts specifies the remote filesystem to be mounted (in our example, nfsserver:/exported/path). Double-click new_directory in Value(s), and enter nfsserver:/exported/path. This specifies what remote filesystem to mount, but nothing else; we need to add a few more properties in this directory.

  5. Under the Directory menu is a command, New Property, which is what we will use to add the properties. Select this command three times, as we'll be specifying the local mount point, mount options, and the mount type.
    Three new properties added
    Three new properties added

  6. Double-click the first new_property and rename it to type; set the value of this property to nfs since we're doing NFS. Change the second new_property to opts, and set the value to a blank (delete what is currently there, also see the note about opts at the end, especially if you experience problems). Change the third new_property to dir and set its value to /private/mnt.
    Properties are now set
    Properties are now set

  7. Save changes. At this point, all necessary information has been loaded into NetInfo for automount to take care of the NFS mount. The only thing left is to inform the automount process that things have changed.

This can, of course, be repeated for other NFS mounts. Run through the steps for each one, then do the final step (notifying automount) after all the mounts have been entered.

NetInfo Changes, Command Line
Adding an NFS mount point via the command line is actually quite simple, once you know the secret. It involves four simple steps, one to create the new NetInfo entry, and three to add the three new properties to that

  1. To create the new entry, run

    sudo nicl . -create /mounts/nfsserver:\\/exported\\/path

    Since NetInfo uses the / to separate path components, and we have / characters in the entry we want to create, they have to be escaped.
    This is done with the backslash, \, and since we are running in a shell, we need to double them up. After the shell is done examining the command, the string \\/ becomes \/ which is what we need to pass to nicl. If we don't use any backslashes, nicl will end up creating an entry /mounts/nfsserver: which has a subdirectory exported and that would have a subdirectory path. This is definitely not what we want.
    Basically, double-backslash the forward slashes in the NFS server's path (/exported/path), but not the NetInfo path (/mounts/).

  2. Now we need to add the three properties which tell automount about this entry. We need type which we set to nfs; opts, set to an empty string (but see the note about opts, below, if you have problems); and dir, set to the local mount point, /private/mnt. This is done:

    sudo nicl . -append /mounts/nfsserver:\\/exported\\/path type nfs
    sudo nicl . -append /mounts/nfsserver:\\/exported\\/path opts ""
    sudo nicl . -append /mounts/nfsserver:\\/exported\\/path dir /private/mnt

    The interesting thing to note is /private/mnt doesn't have any escaped forward slashes. This is due to the data being given to nicl in this case is a value, not a NetInfo path, so we needn't do any escaping this time. These commands simply append the given property to our newly-created NFS entry, and give those properties appropriate values.

  3. The last step is to notify automount that there are changes.

As with the graphical version, this can be repeated for all necessary NFS mounts you need to have on your OS X machine. Add them all, then notify automount.

Final Step: Tell automount
The automount process now needs to be told that new information is available for it to use. You can either simply reboot, or run the following in Terminal:

sudo kill -1 `cat /var/run/`

This will send a HUP signal to the automount process; note those are backticks, not the normal single quote marks. A HUP causes automount to unmount anything not busy, reread configuration, and start anew.

A Few Notes to Know

  • Local mount point, availability
    The first thing to note is the local mount point (once automount takes it) becomes a symlink. It should point to /automount/private/mnt, as that's where automount puts all of its mount points. Then, when the symlink is accessed, automount will live up to its name by automatically mounting the proper NFS server's filesystem. This is one reason why using automount is better than a static mount in some startup script: if the NFS server is down, it won't matter until you try to access the mount; with a static mount, booting up the client will take several minutes while it times out waiting for the down server.

  • opts
    The other thing to note is, if your NFS server requires a client to be coming from a privileged network port (less than 1024), you will need to add -P to the opts property, instead of the empty string. You can also modify the server to allow 'insecure' ports, but using -P doesn't require root access to the server.
    This will be the case with certain BSD-based servers and some Linux ones as well. If the local mount point becomes a symlink (as discussed above), but doesn't have any of the files expected from the server, try adding the -P option, then tell automount. If the mount still doesn't work, there are other issues to deal with (a full NFS troubleshooting discussion is beyond the scope of this document).

  • Viewing /mounts from the command line
    If you want to look at what's currently in /mounts from the command line, run

    nidump -r /mounts .

    This will dump out the information recursively (what's in /mounts, and all the information pertaining to it). It should look something like

    "name" = ( "mounts" );
    CHILDREN = (
    "dir" = ( "/private/mnt" );
    "name" = ( "nfsserver:/exported/path" );
    "type" = ( "nfs" );
    "opts" = ( "" );


  • I had an NFS automount set up in 10.3.9 to my Linux computer, where my music library is stored, but couldn't figure out how to make the transition to Tiger. Thanks for the thorough howto.

    By Anonymous Anonymous, at October 25, 2005 at 7:23 AM  

  • Thanks mate... helped this linux geek with OSX :)

    By Anonymous Anonymous, at October 25, 2005 at 10:05 PM  

  • your helped me very much, thanks.
    but i have the problem that when i shut down the server and accidentily click on a share, Finder freezes. One option is to always run "sudo kill -1 `cat /var/run/`" after connecting/disconnecting from server. Some other suggestions?

    By Anonymous Anonymous, at January 24, 2006 at 5:45 PM  

  • I haven't tried this myself, but perhaps the Finder can handle an interruptible mount. To try it, add the -i option to the opts key to test. See the mount_nfs manpage for info on this switch.

    By Anonymous Anonymous, at February 3, 2006 at 12:55 AM  

  • I have a mount from my linux box with a drive mounted within it, but i cant seem to access the drive in os-x. Any thoughts? i'd appreciate an email at nick AT bonfatti DOT net. Thanks!

    By Anonymous Anonymous, at April 9, 2006 at 5:10 PM  

  • Thanks for your excellent writeup, particularly the other page on setting up an NFS server, which really helped me out.

    I'm curious though, about some of the small differences between your instructions and those given at this page.

    For instance, you use a 'type' field to specify 'nfs', but the other page uses 'vfstype' (which actually doesn't seem to work (anymore?)). Are there resources/documentation for the fields that are expected to exist for each mount (theoretically Apple should provide official documentation on such things?)

    Thanks! ejt AT andrew cmu edu

    By Anonymous Anonymous, at June 21, 2006 at 12:41 PM  

  • nice writeup

    By Anonymous Anonymous, at June 25, 2006 at 3:15 PM  

  • Great page!

    Any help on troubleshooting

    NFS with the Mac to a Linux server env. (..and lets throw in ldap for fun!)...


    By Anonymous Anonymous, at July 3, 2006 at 11:20 AM  

  • What if the NFS server requires authentication?

    By Anonymous Anonymous, at September 20, 2006 at 4:57 PM  

  • Thanks for the explanation, but after setting up NetInfo as explained the Finder gives the message that the alias file does not exist and Terminal gives the message Resource busy.

    Any idea why? Help is very much appreciated as it is very difficult to find information on the web.

    By Anonymous Anonymous, at October 14, 2006 at 5:18 AM  

  • You can add the 'net' option and the automounter will mount the filesystem under /Network/Servers/servername. This means there's only one thing to modify when adding a new mount ... here's my mount table, for example:

    "name" = ( "mounts" );
    CHILDREN = (
    "type" = ( "nfs" );
    "name" = ( "" );
    "opts" = ( "resvport,ro,net" );
    "type" = ( "nfs" );
    "name" = ( "" );
    "opts" = ( "resvport,ro,net" );

    (sorry for the ugliness, but I guess commenters can't use PRE and so forth)

    By Anonymous Anonymous, at December 3, 2006 at 6:19 PM  

  • thanks for the howto! very helpful indeed.

    By Anonymous Anonymous, at January 3, 2007 at 2:39 PM  

  • I'm looking through documentation on NFS from various sources, and I see no mention of authentication anywhere, this is too bad as NFS is much faster, in my experience, than smb or afp.

    In the organization I work at currently, they have NFS exports for a shared productivity folder, and I can mount it, but only as a readable volume. To read/write I need to attach it via smb or afp.

    Is there any way to export nfs volumes with authentication so that it would be exported with read only to non-authenticated users, and with read/write to those who authenticate?

    By Anonymous Anonymous, at January 23, 2007 at 1:34 PM  

  • Thanks very much for this post. The automounting did not work for me on 10.4.8 exactly as you described it, but it did with "net" as the value for the "opts" property, ie.

    $ nidump -r /mounts .
    "name" = ( "mounts" );
    CHILDREN = (
    "type" = ( "nfs" );
    "dir" = ( "/private/mnt" );
    "opts" = ( "net" );
    "name" = ( "" );

    By Anonymous Anonymous, at February 21, 2007 at 2:36 PM  

  • I don't think there's any way to authenticate via NFS. NFS uses the numeric user/group IDs, and does not map them in any way.

    To see your numeric user and group IDs on your desktop (any computer where you're logged in), open a Terminal window and type "id". You'l see something like
    uid=501(yourname) gid=501(yournameagain)...
    Your user and group IDs are both 501 (they're different things, even though OS X happens to choose the same number for them, often).

    To see your numeric user and group IDs on your file server, mount it read-only, open a Terminal, cd into the directory, and type "ls -ln". You'll see a bunch of lines like
    -rw-r--r-- 1 7023 4001 189616 Jan 26 12:25 foo

    In this example, my UID on the server is 7023; my GID is 4001.

    If you only need to access one NFS server, it is possible to change your uid/gid on your desktop to match the server, but it's not simple (comparable to these directions for doing the mount in the first place).

    If you need to access more than one NFS server, then this only works if all the servers and your desktop assign you the same numeric ID.

    A brief sketch of the conversion process:

    Log in as some administrative account *other* than the one you plan to change (which may require creating such an account).

    In Netinfo (either GUI or command line, as described in the main article), change the uid and gid for your "user" to the number shown on the server.

    Also in Netinfo, change the gid of your "group" to match the server.

    In Terminal,
    sudo find / -user OLDUIDNUMBER -exec chown \{} NEWUIDNUMBER \;
    sudo find / -group OLDGIDNUMBER -exec chgrp \{} NEWGIDNUMBER \;

    (read those commands carefully, keeping "OLD" and "NEW" straight, as well as "U"ID and "G"ID)


    By Anonymous Anonymous, at February 22, 2007 at 12:07 PM  

  • To update anonymous, I think the command you gave above for sudo find / -user XXX should be more like:

    sudo find / -user OLD_USER_ID -exec chown NEW_USER_NAME {} \;
    sudo find / -group OLD_GROUP_ID -exec chgrp NEW_GROUP_NAME {} \;

    This may have to do with having bash as the root user's shell, or not, I'm not sure, or using tcsh as your main shell (which I do).

    The error I received was:

    find: -exec: no terminating ";"

    I think the shell stripped it out so it has to be escaped.

    If you have a simple permissions set up (nothing shared), then a single command will do, like so:

    sudo find / -user OLD_USER_ID -exec chown NEW_USER_NAME:NEW_USER_GROUP_NAME {} \;

    Thanks for the great article...

    By Blogger Unknown, at July 10, 2007 at 12:45 PM  

  • Thanks for the great write-up.

    One question - I have asituation which is somewhat difficult to describe, but in a word, from boot to boot I would be able to mount some partitions and not others. Other machines can mount to the same servers just fine, the network is quite stable overall. Any idea what could be the problem with my Macs? The are all running MacOS 10.


    By Blogger Boris Epstein, at September 13, 2007 at 11:03 AM  

  • Am trying to do what others have done - use Mac OS 10.4 to access music files on an Ubuntu volume. Am reasonably sure the NFS & SMB shares are properly defined on the Ubuntu machine.

    I followed the steps as noted in the article in NetInfo Manager - am going to try entering those terminal commands. One very basic question: those terminal commands are to be entered in the MAC terminal, NOT the linux-ubuntu terminal, correct?

    Just making sure!


    By Blogger will friedwald, at September 30, 2007 at 12:28 PM  

  • This doesn't work for me... I'm trying to mount a set of home directories (as I have on a bunch of Debian 4.0 GNU/Linux machines), and I get told I don't have the right password. AFAICR, I didn't need to use a password on the Linux machines (yes, I know this is insecure). I'm guessing the Mac needs to pretend it's mounting as UID 0?

    By Anonymous Anonymous, at October 6, 2007 at 10:24 AM  

  • Change uid to mount the nfs server??
    That's kinda crazy, and not very safe thing -- you can really mess things up. Isn't it MUCh easier, on the nfs side, to do uid mapping? in exports file specify

    nfs_server:/dir_toexport client(rw,map_stati=/etc/

    where should simply consist of
    uid 501 1000

    this will statically map uid 501 on the Mac side to 1000 (or whatever it is the uid of the owner of the /dir_toexport).

    By Anonymous Anonymous, at November 30, 2007 at 3:01 PM  

  • Sorry, the exports file line should be

    /dir_toexport client(rw,map_static=/etc/

    By Anonymous Anonymous, at November 30, 2007 at 3:04 PM  

  • Good Job! :)

    By Anonymous Anonymous, at June 28, 2008 at 4:42 AM  

  • i set up my nfs server using this tutorial on my ubuntu hardy heron linux box:

    and now I'm trying to use this tutorial to access it from my 10.4.11 mac os box, using the tutorial and reading the comments about uid i tried using the map_static in the exports file but it's not a valid command, so I'm stuck is there any other way?

    By Blogger Unknown, at August 12, 2008 at 10:40 PM  

  • and to add to my previous statement i added "net" in "opts" and it does show up but the files inside do not, just the path

    By Blogger Unknown, at August 12, 2008 at 10:43 PM  

  • I got nfs to work! i can see my entire music library now as root. but how do i get this to work with itunes? their is no link on my desktop to the directory is there a way to put one there? sorry bit of a mac nub...

    By Anonymous Anonymous, at February 17, 2009 at 12:07 PM  

  • Do you know if long file names are supported when saving data to an NFS mount point?

    By Blogger Unknown, at March 26, 2010 at 1:03 PM  

  • This comment has been removed by the author.

    By Blogger Dima, at April 12, 2010 at 9:13 PM  

  • An other very useful blog post by MacTechNotes.

    Thanks for sharing your knowledge with us.

    I am a big fan of your blog because your articles are clear and simple to read even for a noobie like me.

    Thanks again.

    best wishes

    By Anonymous strongvpn, at May 30, 2011 at 1:10 PM  

  • Dude you rock! We have an antiquated OS-X 8.11 box and our Apple admins have struggled to try to create an nfs mount to our Linux box. Ended up saying it couldn't be done till OS-X 10.

    By Anonymous Anonymous, at April 4, 2013 at 2:27 PM  

Post a Comment

<< Home